Call a tool

POST 
/api/v1/tools/:tool_id/call

Directly invokes a tool and returns its output. Supported for http, soat, mcp, and pipeline tools. client tools cannot be invoked server-side and will return 422. A pipeline tool runs its declared steps in order and returns the mapped output (or the last step's output); action is ignored and input is the pipeline input. For soat and mcp tools the action field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For http tools action is ignored. When a soat or mcp tool declares an actions allowlist, an action outside it is rejected with 400 VALIDATION_FAILED ("not available on this tool") before any outbound request is made. preset_parameters stored on the tool are merged with the caller-supplied input before execution; preset keys take lower precedence.

Request

Responses

200

Tool output

400

Bad Request — invalid input or unknown action

401

Unauthorized

403

Forbidden

404

Tool not found

422

Unprocessable — tool type cannot be invoked server-side

502

Upstream tool target error (TOOL_HTTP_ERROR). Returned when an http-type tool's target responds with a non-2xx status. The error meta carries the real upstream tool_status_code, tool_response_body, tool_url, and tool_method.