Tool Invocation

A tool invocation is a message sent from the runtime to a tool, requesting that the tool execute an operation. The runtime dispatches invocations as HTTP POST requests to the tool's registered endpoint.

Request

The runtime MUST send a tool invocation as an HTTP POST with Content-Type: application/json.

POST https://tool.example.com/invoke
Content-Type: application/json

{
  "operation": "subscribe_github_events",
  "arguments": {
    "owner": "acme",
    "repo": "api",
    "event_type": "pull_request"
  },
  "id": "call_abc123",
  "call_id": null,
  "callback_url": "https://agent.example.com/callback",
  "group_id": "thread_xyz",
  "thread_ancestors": ["thread_root", "thread_parent"],
  "user_id": "user_42"
}

Fields

Field	Type	Required	Description
operation	string	Yes	The tool operation name. MUST match a name defined in the tool's toolset definition.
arguments	object	Yes	Tool arguments. MUST conform to the JSON Schema defined for this operation in the toolset.
id	string	Yes	Unique tool call identifier, typically generated by the LLM. MUST be included in the corresponding tool result.
call_id	string | null	No	Optional secondary call identifier for model-specific tracking. If provided, MUST be echoed in the tool result.
callback_url	string	Yes	The URL where the tool MUST POST results. See Transport for callback URL requirements.
group_id	string	Yes	Conversation thread identifier. MUST be included in all callback messages to route them to the correct conversation.
thread_ancestors	string[] | null	No	Ordered list of ancestor thread group IDs, from root to the parent of the current thread. Tools MAY use this to inherit state (e.g. permission grants) from parent threads. Omitted when the current thread is the root.
user_id	string | null	No	End-user identity. Tools MAY use this for authorization, personalization, or audit logging.

Response

The tool MUST return HTTP 200 immediately to acknowledge receipt. The response body is not read by the runtime.

HTTP/1.1 200 OK

The tool MUST NOT block the HTTP response on processing the invocation. The acknowledgement confirms only that the message was received and will be processed.

Processing

After acknowledging the invocation, the tool:

1. MUST process the request asynchronously
2. MUST send a result to the callback_url when processing completes, using one of the callback message types
3. MAY take arbitrarily long to process — the protocol defines no timeout

If the tool encounters an error during processing, it MUST still send a tool result with the error description. The tool MUST NOT silently drop invocations.

Validation

Runtime Validation

Before dispatching an invocation, the runtime MUST verify that the operation field matches a known tool definition from a loaded toolset. The runtime SHOULD validate the arguments object against the tool's inputSchema to catch malformed input before it reaches the tool. The runtime MUST generate a unique id for the tool call (or use the one provided by the LLM), MUST provide a valid callback_url where the tool can deliver results, and MUST include the group_id of the current conversation thread. When the current thread has ancestor threads, the runtime SHOULD include thread_ancestors with the ordered list of ancestor group IDs from root to parent.

Tool Validation

Upon receiving an invocation, the tool MUST validate that the operation field references a supported operation. For any validation failure — malformed payload, unknown operation, invalid arguments — the tool SHOULD still return HTTP 200 to acknowledge receipt, then deliver the error asynchronously as a tool result with an error description.

Error Responses

The protocol intentionally keeps the HTTP-level error surface minimal. Tools MUST return HTTP 200 if they accept the invocation for asynchronous processing. Any other non-200 status indicates the tool could not accept the invocation, and the runtime SHOULD record the failure as a tool result with an error description, allowing the LLM to reason about it.

Detailed error information (invalid arguments, authorization failures, rate limits) SHOULD be communicated asynchronously via a tool result with an error description, not through HTTP status codes.

Security Considerations

Tools MUST validate all input arguments before processing to guard against injection attacks, unexpected data types, or values outside acceptable ranges. Tools that use the user_id field for authorization decisions MUST implement proper access controls to ensure users can only perform operations they are permitted to.

Tools SHOULD rate-limit invocations to prevent abuse, and SHOULD sanitize output before sending results to the callback URL to avoid leaking internal implementation details. Runtimes SHOULD log tool invocations for audit purposes, including the operation name, timestamp, and outcome.