Skip to main content
Execute one tool and return its result.

​
Request

In Discovery or Unified presentation mode, call the meta-tool (execute_tool or unified_tool) rather than the underlying tool — the underlying names are not directly callable in those modes.

​
Response

​
What happens before your tool runs

Five checks run in order, and each has a distinct failure shape. The first two happen at the transport, before the method is dispatched, so they fail as HTTP statuses rather than JSON-RPC errors.
1

Authentication

Handled at the transport. A failure never reaches this method — see Authentication.
2

Billing state

Also at the transport, on every request the gateway admits. An account with no available budget gets HTTP 402; a billing check that cannot complete gets HTTP 503. Neither carries a JSON-RPC body.
3

Rate limit

600 requests per minute per gateway per caller, shared with tools/list. Exceeded returns JSON-RPC -32029. The separate initialize handshake limit does not apply to tools/call.
4

Budget allocation

A budget is allocated against the account for this specific call. No available budget — a hard stop, a zero balance, or an exceeded spending cap — returns JSON-RPC -32600 at HTTP 200, reading "Account has insufficient credits or has been suspended".
5

Autonomy

The call passes through the admission door. On an MCP gateway this can only allow or deny; it cannot pause. See below.
Budget is checked twice on a tools/call: once as a transport-level account state (402) and once as a per-call allocation (-32600). A client needs to handle both shapes.

​
Autonomy on this surface

MCP is an unattended surface. There is no live channel to ask a human for approval, so a call that would pause for approval denies instead, with the reason non_interactive_surface. Check the _meta["dev.noorle/autonomy"].outcome on the tool listing before offering a tool to a model: The annotation is a hint the gate re-evaluates at dispatch — a stale allow can still deny.

​
Errors

An unknown or unexposed tool name returns an invalid-tool-name error.
A withheld tool returns the same error as a nonexistent one. Calling a tool that requires a workspace anchor you do not have — file_*, sandbox_*, or Browser’s screenshot / pdf / snapshot as an anonymous caller — returns the identical invalid-tool-name shape as a tool that does not exist. The response deliberately does not confirm the tool is there.
Some failures carry a structured data payload rather than only a message:

​
Timeouts

The gateway enforces a 240-second request timeout, after which it returns 504. Individual capabilities have their own, shorter limits — a WASM plugin’s execution timeout defaults to 30 seconds and is capped at 120.