Call a tool

POST 
/v1/projects/:project_id/tools/:tool_id/call

Directly invokes a tool and returns its output. Supported for http, 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 mcp tools the action field is required and identifies which tool name to invoke. For http tools action is ignored. When an 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.

A credential scoped to a project the tool is shared with, through an accepted share, calls it in that project: the calling project's guardrails adjudicate it, it is metered there with publisher_project_id, and the tool receives the calling project as the calling_project_id tool context key.

Request

Responses

200

Tool output

400

Bad Request — invalid input or unknown action

401

Unauthorized

403

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.

404

Tool not found

422

Unprocessable — tool type cannot be invoked server-side

429

SHARE_CAP_EXCEEDED: the tool is another project's, reached through a share whose cap is spent for the window. Carries a Retry-After header and error.meta.retry_after.

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.