ToolCall
A single structured tool call emitted by the model
clientToolDeadlineAt is the client answer
window. Expiry ends that wait and rejects late results; the timeout policy determines the outcome.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
| In webhook payloads | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | Optional | Provider-supplied call id. |
name | string | Optional | Name of the tool or function being invoked. |
argumentsJson | Map from string to JSON value | Optional | JSON object payload. |
status | string (TOOL_EXECUTION_STATUS_PENDING, TOOL_EXECUTION_STATUS_EXECUTING, TOOL_EXECUTION_STATUS_COMPLETED, TOOL_EXECUTION_STATUS_SUCCESS, TOOL_EXECUTION_STATUS_FAILED, TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION, TOOL_EXECUTION_STATUS_CANCELLED, TOOL_EXECUTION_STATUS_TIMED_OUT) or integer (int32) | Optional | Execution status recorded for the tool call. |
resultJson | Map from string to JSON value | Optional | Tool execution result (object). |
executedAt | string (date-time) | Optional | Time when the tool execution was recorded. |
serverId | string | Optional | Which server provides this tool (for MCP tools). |
isClientTool | boolean | Optional | True if this is a client-side tool handled by client. |
description | string | Optional | Tool description captured when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. |
parametersJsonSchema | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. |
requiresApprovalAt | string (date-time) | Optional | Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. |
approvedAt | string (date-time) | Optional | Timestamp when approval decision was recorded (if approved/rejected) |
approvedBy | string | Optional | Identifier of the approver (user id, email, or actor key) |
executionDuration | string | Optional | End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:.[0-9]{1,9})?s$. |
endReason | string | Optional | Why this call ended, in one short phrase — "approval rejected", "approval timeout", the underlying error. Set only once status is terminal, and empty on a clean COMPLETED. |
clientToolDeadlineAt | string (date-time) | Optional | Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. Mirrors requires_approval_at. |
Values of status
Execution state of one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_EXECUTION_STATUS_PENDING | 1 | Canonical | The tool call is waiting to begin execution. |
TOOL_EXECUTION_STATUS_EXECUTING | 2 | Canonical | The tool call is currently executing. |
TOOL_EXECUTION_STATUS_COMPLETED | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
TOOL_EXECUTION_STATUS_SUCCESS | 3 | Alias of TOOL_EXECUTION_STATUS_COMPLETED | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
TOOL_EXECUTION_STATUS_FAILED | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION | 5 | Canonical | The tool call is waiting for approval before it can execute. |
TOOL_EXECUTION_STATUS_CANCELLED | 6 | Canonical | The tool call was cancelled before normal completion. |
TOOL_EXECUTION_STATUS_TIMED_OUT | 7 | Canonical | Tool execution ended because its time limit elapsed. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | Optional | Provider-supplied call id. |
name | string | Optional | Name of the tool or function being invoked. |
argumentsJson | Map from string to JSON value | Optional | JSON object payload. |
status | string (TOOL_EXECUTION_STATUS_PENDING, TOOL_EXECUTION_STATUS_EXECUTING, TOOL_EXECUTION_STATUS_COMPLETED, TOOL_EXECUTION_STATUS_FAILED, TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION, TOOL_EXECUTION_STATUS_CANCELLED, TOOL_EXECUTION_STATUS_TIMED_OUT) or integer (int32) | Optional | Execution status recorded for the tool call. |
resultJson | Map from string to JSON value | Optional | Tool execution result (object). |
executedAt | string (date-time) | Optional | Time when the tool execution was recorded. |
serverId | string | Optional | Which server provides this tool (for MCP tools). |
isClientTool | boolean | Optional | True if this is a client-side tool handled by client. |
description | string | Optional | Tool description captured when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. |
parametersJsonSchema | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. |
requiresApprovalAt | string (date-time) | Optional | Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. |
approvedAt | string (date-time) | Optional | Timestamp when approval decision was recorded (if approved/rejected) |
approvedBy | string | Optional | Identifier of the approver (user id, email, or actor key) |
executionDuration | string | Optional | End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:.[0-9]{1,9})?s$. |
endReason | string | Optional | Why this call ended, in one short phrase — "approval rejected", "approval timeout", the underlying error. Set only once status is terminal, and empty on a clean COMPLETED. |
clientToolDeadlineAt | string (date-time) | Optional | Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. Mirrors requires_approval_at. |
Values of status
Execution state of one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_EXECUTION_STATUS_PENDING | 1 | Canonical | The tool call is waiting to begin execution. |
TOOL_EXECUTION_STATUS_EXECUTING | 2 | Canonical | The tool call is currently executing. |
TOOL_EXECUTION_STATUS_COMPLETED | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
TOOL_EXECUTION_STATUS_SUCCESS | 3 | Alias of TOOL_EXECUTION_STATUS_COMPLETED; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
TOOL_EXECUTION_STATUS_FAILED | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION | 5 | Canonical | The tool call is waiting for approval before it can execute. |
TOOL_EXECUTION_STATUS_CANCELLED | 6 | Canonical | The tool call was cancelled before normal completion. |
TOOL_EXECUTION_STATUS_TIMED_OUT | 7 | Canonical | Tool execution ended because its time limit elapsed. |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | Optional | Provider-supplied call id. |
name | string | Optional | Name of the tool or function being invoked. |
arguments_json | Map from string to JSON value | Optional | JSON object payload. |
status | string (TOOL_EXECUTION_STATUS_PENDING, TOOL_EXECUTION_STATUS_EXECUTING, TOOL_EXECUTION_STATUS_COMPLETED, TOOL_EXECUTION_STATUS_FAILED, TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION, TOOL_EXECUTION_STATUS_CANCELLED, TOOL_EXECUTION_STATUS_TIMED_OUT) or integer (int32) | Optional | Execution status recorded for the tool call. |
result_json | Map from string to JSON value | Optional | Tool execution result (object). |
executed_at | string (date-time) | Optional | Time when the tool execution was recorded. |
server_id | string | Optional | Which server provides this tool (for MCP tools). |
is_client_tool | boolean | Optional | True if this is a client-side tool handled by client. |
description | string | Optional | Tool description captured when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. |
parameters_json_schema | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. |
requires_approval_at | string (date-time) | Optional | Deadline for an approval decision, calculated from the effective approval timeout. This is not the time the call began waiting. An approval received after the deadline is rejected. |
approved_at | string (date-time) | Optional | Timestamp when approval decision was recorded (if approved/rejected) |
approved_by | string | Optional | Identifier of the approver (user id, email, or actor key) |
execution_duration | string | Optional | End-to-end execution duration once terminal (includes tool server latency or client-side time) Pattern: ^-?(?:0|[1-9][0-9]*)(?:.[0-9]{1,9})?s$. |
end_reason | string | Optional | Why this call ended, in one short phrase — "approval rejected", "approval timeout", the underlying error. Set only once status is terminal, and empty on a clean COMPLETED. |
client_tool_deadline_at | string (date-time) | Optional | Deadline by which the client must submit a result for this call, stamped when the call is dispatched to a caller. Mirrors requires_approval_at. |
Values of status
Execution state of one tool call, including approval waiting and terminal outcomes.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_EXECUTION_STATUS_PENDING | 1 | Canonical | The tool call is waiting to begin execution. |
TOOL_EXECUTION_STATUS_EXECUTING | 2 | Canonical | The tool call is currently executing. |
TOOL_EXECUTION_STATUS_COMPLETED | 3 | Canonical | The tool call completed successfully. Responses use this canonical spelling for numeric value 3. |
TOOL_EXECUTION_STATUS_SUCCESS | 3 | Alias of TOOL_EXECUTION_STATUS_COMPLETED; Name not accepted for this field; number accepted | Legacy alias of TOOL_EXECUTION_STATUS_COMPLETED with the same numeric value; use COMPLETED for new writes. |
TOOL_EXECUTION_STATUS_FAILED | 4 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION | 5 | Canonical | The tool call is waiting for approval before it can execute. |
TOOL_EXECUTION_STATUS_CANCELLED | 6 | Canonical | The tool call was cancelled before normal completion. |
TOOL_EXECUTION_STATUS_TIMED_OUT | 7 | Canonical | Tool execution ended because its time limit elapsed. |
Where used
| Reference | Relationship |
|---|---|
| Append a message without generating | POST /api/v1/llm/append-message |
| Execute an MCP tool | POST /api/v1/llm/mcp-call-tool |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Get a single tool call by ID | POST /api/v1/llm/get-tool-call |
| List pending tool approvals | POST /api/v1/llm/list-pending-approvals |
| List client-side tool calls awaiting a result | POST /api/v1/llm/list-pending-client-tools |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| llm.tool_call_approval_required | Webhook JSON uses protobuf field names (snake_case). |
| llm.tool_call_completed | Webhook JSON uses protobuf field names (snake_case). |
| llm.tool_call_started | Webhook JSON uses protobuf field names (snake_case). |
| Message | Nested in model |
| Message | Nested in model |
| Message | Nested in model |
| ToolCallCompletedEvent | Nested in model |
| ToolCallStartedEvent | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-tool-call.