Call a tool
POST/api/v1/tools/:tool_id/call
Directly invokes a tool and returns its output. Supported for http, builtin, 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 builtin 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 builtin 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 pinned over the caller-supplied input before execution: a key the tool presets keeps its preset value even when input sets it. Keys the presets do not name are taken from input as sent.
Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with 422 TOOL_DISPATCH_FAILED, whose meta carries the tool_id and the outcome. A pipeline tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 502
Tool output
Bad Request — invalid input or unknown action
Unauthorized
Forbidden — the caller lacks permission, or the tool's target is blocked by the deployment's egress policy (TOOL_EGRESS_BLOCKED). An http/mcp tool may only reach publicly routable addresses unless the destination is listed in the server's TOOL_EGRESS_ALLOWED_HOSTS; the check runs against the resolved address and on every redirect hop, so meta.tool_address names the address that was refused.
Tool not found
Unprocessable — tool type cannot be invoked server-side
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.