Section ID:
Values of
Values of
DOC-API-MODEL-schema-1it6mqsqoo#overview
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.
Type-reference view: API Schema 9frhv4euve, API Schema 9ftjkkjhfa. Request and response views describe this type; they do not declare an endpoint.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-idid | string | Optional | Provider-supplied call id. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-namename | string | Optional | Name of the tool or function being invoked. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-argumentsjsonargumentsJson | Map from string to JSON value | Optional | JSON object payload. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-statusstatus | 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; explicit presence | Execution status recorded for the tool call. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-resultjsonresultJson | Map from string to JSON value | Optional | Tool execution result (object). |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-executedatexecutedAt | string (date-time) | Optional | Time when the tool execution was recorded. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-serveridserverId | string | Optional | Which server provides this tool (for MCP tools). |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-isclienttoolisClientTool | boolean | Optional | True if this is a client-side tool handled by client. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-descriptiondescription | string | Optional | Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-parametersjsonschemaparametersJsonSchema | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-requiresapprovalatrequiresApprovalAt | 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. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-approvedatapprovedAt | string (date-time) | Optional | Timestamp when approval decision was recorded (if approved/rejected) |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-approvedbyapprovedBy | string | Optional | Identifier of the approver (user id, email, or actor key) |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-executiondurationexecutionDuration | 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$. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-endreasonendReason | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-field-clienttooldeadlineatclientToolDeadlineAt | 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. |
endReason
Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once status is terminal, and empty on a clean COMPLETED.
Use this reason to distinguish a rejection from a failure without parsing the tool result.
Values of status
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#request-values-status
Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED_OUT; inspect ToolCall.end_reason for why a call ended rather than treating the reason as another status.
Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_EXECUTION_STATUS_PENDING | 0 | Canonical | The tool call is waiting to begin execution. |
TOOL_EXECUTION_STATUS_EXECUTING | 1 | Canonical | The tool call is currently executing. |
TOOL_EXECUTION_STATUS_COMPLETED | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. |
TOOL_EXECUTION_STATUS_FAILED | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION | 4 | Canonical | The tool call is waiting for approval before it can execute. |
TOOL_EXECUTION_STATUS_CANCELLED | 5 | Canonical | The tool call was cancelled before normal completion. |
TOOL_EXECUTION_STATUS_TIMED_OUT | 6 | Canonical | Tool execution ended because its time limit elapsed. |
In responses
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-idSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-idid | string | Optional | Provider-supplied call id. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-nameSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-namename | string | Optional | Name of the tool or function being invoked. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-argumentsjsonSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-argumentsjsonargumentsJson | Map from string to JSON value | Optional | JSON object payload. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-statusSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-statusstatus | 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; explicit presence | Execution status recorded for the tool call. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-resultjsonSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-resultjsonresultJson | Map from string to JSON value | Optional | Tool execution result (object). |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-executedatSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-executedatexecutedAt | string (date-time) | Optional | Time when the tool execution was recorded. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-serveridSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-serveridserverId | string | Optional | Which server provides this tool (for MCP tools). |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-isclienttoolSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-isclienttoolisClientTool | boolean | Optional | True if this is a client-side tool handled by client. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-descriptionSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-descriptiondescription | string | Optional | Tool description captured from the resolved tool definition when the call is emitted, preserving the definition used for historical calls even if the tool configuration later changes. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-parametersjsonschemaSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-parametersjsonschemaparametersJsonSchema | Map from string to JSON value | Optional | JSON Schema describing the tool’s input arguments. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-requiresapprovalatSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-requiresapprovalatrequiresApprovalAt | 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. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-approvedatSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-approvedatapprovedAt | string (date-time) | Optional | Timestamp when approval decision was recorded (if approved/rejected) |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-approvedbySection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-approvedbyapprovedBy | string | Optional | Identifier of the approver (user id, email, or actor key) |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-executiondurationSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-executiondurationexecutionDuration | 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$. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-endreasonSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-endreasonendReason | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#field-clienttooldeadlineatSection ID: DOC-API-MODEL-schema-1it6mqsqoo#response-field-clienttooldeadlineatclientToolDeadlineAt | 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. |
endReason
Why this call ended, in one short phrase — "approval rejected", "approval timeout", or the underlying error. Set only once status is terminal, and empty on a clean COMPLETED.
Use this reason to distinguish a rejection from a failure without parsing the tool result.
Values of status
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#response-values-status
Execution state of a tool call, including approval waiting and terminal outcomes. The terminal outcomes are COMPLETED, FAILED, CANCELLED and TIMED_OUT; inspect ToolCall.end_reason for why a call ended rather than treating the reason as another status.
Use a listed execution status. The end reason explains the outcome separately from the status.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_EXECUTION_STATUS_PENDING | 0 | Canonical | The tool call is waiting to begin execution. |
TOOL_EXECUTION_STATUS_EXECUTING | 1 | Canonical | The tool call is currently executing. |
TOOL_EXECUTION_STATUS_COMPLETED | 2 | Canonical | The tool call completed successfully. This is a terminal outcome. |
TOOL_EXECUTION_STATUS_FAILED | 3 | Canonical | Tool execution ended unsuccessfully; inspect the tool error or end reason. |
TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION | 4 | Canonical | The tool call is waiting for approval before it can execute. |
TOOL_EXECUTION_STATUS_CANCELLED | 5 | Canonical | The tool call was cancelled before normal completion. |
TOOL_EXECUTION_STATUS_TIMED_OUT | 6 | Canonical | Tool execution ended because its time limit elapsed. |
Where used
Section ID: DOC-API-MODEL-schema-1it6mqsqoo#where-used
| Reference | Relationship |
|---|---|
| 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 |
| Execute an MCP tool | POST /api/v1/llm/mcp-call-tool |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| Append a message without generating | POST /api/v1/llm/append-message |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| Message | Nested in model |
| Message | Nested in model |
| ToolCallCompletedEvent | Nested in model |
| ToolCallCompletedEvent | Nested in model |
| ToolCallStartedEvent | Nested in model |
| ToolCallStartedEvent | Nested in model |
| ClientToolDispatch | Nested in model |
| ClientToolDispatch | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1it6mqsqoo