Call a tool
POST/v1/projects/:project_id/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 (builtin) 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.
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.
actor_id runs the call for an actor without a session or a generation, such as a scheduled sync reading each user's own data through their OAuth connection.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 413
- 422
- 429
- 500
- 502
- 4XX
Tool output
Bad Request — invalid input or unknown action; VALIDATION_FAILED when the input does not satisfy the tool's parameters.
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
PROJECT_PAUSED — the project is paused, so nothing new starts in it; error.meta carries paused_at and pause_reason. OAUTH_CONNECTION_REQUIRED — an oauth_connection tool ran for an actor holding no connected connection through its oauth_client_id; error.meta carries oauth_client_id, actor_id and, when one exists, oauth_connection_id.
REQUEST_REJECTED — the request body is over the size the body parser accepts
Unprocessable — tool type cannot be invoked server-side
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.
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
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. A target that never answers (http or mcp) is TOOL_UNREACHABLE, its message naming the network failure and its meta the tool_url and tool_method. An mcp tool whose server answers a failure is MCP_TOOL_ERROR, meta carrying mcp_tool, mcp_url and, when the failed result carries the REST error envelope as structuredContent, upstream_status, upstream_code, upstream_message and upstream_meta. A builtin action answers its error as its REST call does, under its own status and code.
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there