DOC-API-MODEL-schema-1h2ji21uc4#overview
ToolExecutionPolicy
Per-run policy for approvals, MCP execution concurrency, admitted tool-call budget and answer windows. Some stored controls are not enforced by the current workflow.
If an expected approval does not appear, inspect the tool/server require rules and auto-approve exceptions. Auto-approve takes precedence; server IDs are compared case-insensitively after trimming whitespace. An exception does not establish that the user reviewed the action.
An omitted or zero approvalTimeoutMs waits five minutes. At expiry, failOnApprovalTimeoutToolNamePatterns yields FAILED for matching calls and TIMED_OUT for others; an unset list makes every expiry FAILED.
The retry controls retriableToolNamePatterns, retryableErrorSubstrings, nonRetryableErrorSubstrings, maxRetries and retryBackoff are stored but do not schedule retries. Ordering rules, tie-breaking, the per-loop call cap, client-tool scheduling mode, failure mode and stop-on-failure rules are also not enforced; do not rely on them as execution or safety controls.
maxTotalToolCalls limits admitted calls across the run; zero or omission leaves the cap unset. A client call consumes budget when armed. A routable MCP call consumes budget before approval, including when held for approval or later rejected. Unknown tools and calls refused because the cap is already exhausted do not consume budget. Further calls at the limit receive FAILED tool results naming the limit, which the model can use when continuing the run.
maxParallelToolCalls limits concurrent MCP execution. Zero or one runs MCP calls sequentially; values greater than one permit concurrency. Client calls are armed separately, and your application controls their execution concurrency.
Choose clientToolTimeoutMs for your application's validation and action. Zero or omission gives a five-minute answer window; there is no unbounded setting. Each call returns its resolved clientToolDeadlineAt.
See Tool execution policies for policy selection and caller reconciliation.
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-1h2ji21uc4#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-requireapprovaltoolnamepatternsrequireApprovalToolNamePatterns | Array of string | Optional | Tool-name patterns selecting calls that require an approval decision. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-requireapprovalserveridsrequireApprovalServerIds | Array of string | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-autoapprovetoolnamepatternsautoApproveToolNamePatterns | Array of string | Optional | Tool-name patterns whose matching calls may be approved automatically. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-autoapproveserveridsautoApproveServerIds | Array of string | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-approvalmodeapprovalMode | string (APPROVAL_MODE_MIXED, APPROVAL_MODE_BLOCK_ALL) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-clienttoolmodeclientToolMode | string (CLIENT_TOOL_MODE_MIXED, CLIENT_TOOL_MODE_BLOCK_ALL) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-approvaltimeoutmsapprovalTimeoutMs | string (int64) | Optional | Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED; other calls become TIMED_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-failonapprovaltimeouttoolnamepatternsfailOnApprovalTimeoutToolNamePatterns | Array of string | Optional | Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT. An empty list makes every approval expiry FAILED. Global failure_mode is not enforced. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-orderrulesorderRules | Array of ToolExecutionOrderRule | Optional | Stored requested ordering rules; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-stablesortbycallindexontiestableSortByCallIndexOnTie | boolean | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-maxparalleltoolcallsmaxParallelToolCalls | string (int64) | Optional | Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-maxtoolcallsperloopmaxToolCallsPerLoop | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-maxtotaltoolcallsmaxTotalToolCalls | string (int64) | Optional | Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-retriabletoolnamepatternsretriableToolNamePatterns | Array of string | Optional | Stored requested retry selection; does not enable retries in the current workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-maxretriesmaxRetries | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-retrybackoffretryBackoff | Backoff | Optional | Stored requested retry delays; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-retryableerrorsubstringsretryableErrorSubstrings | Array of string | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-nonretryableerrorsubstringsnonRetryableErrorSubstrings | Array of string | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-timeoutstimeouts | TimeoutPolicy | Optional | Overall execution time budget for the generation run. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-clienttooltimeoutmsclientToolTimeoutMs | string (int64) | Optional | Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-failuremodefailureMode | string (FAILURE_MODE_CONTINUE, FAILURE_MODE_STOP_LOOP, FAILURE_MODE_STOP_RUN) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-field-stoponfailurerulesstopOnFailureRules | Array of StopOnFailureRule | Optional | Stored requested stop rules; not evaluated by the current generation workflow. |
approvalMode
How to schedule execution when approvals are required for some tools
default: APPROVAL_MODE_MIXED
clientToolMode
Stored requested client-tool scheduling mode; not enforced by the current workflow.
default: CLIENT_TOOL_MODE_MIXED
maxToolCallsPerLoop
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
0 = no cap
maxRetries
Stored requested retry count; does not enable retries in the current workflow.
per tool-call
failureMode
Stored requested failure action; not enforced by the current generation workflow.
default if no rule matches
Values of approvalMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-values-approvalmode
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
APPROVAL_MODE_MIXED | 0 | Canonical | See meaning below. |
APPROVAL_MODE_BLOCK_ALL | 1 | Canonical | See meaning below. |
APPROVAL_MODE_MIXED
Run automatically approved calls immediately and hold only calls that require approval.
Run auto-approved tool calls immediately; hold only those requiring approval.
APPROVAL_MODE_BLOCK_ALL
Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected.
Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Values of clientToolMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-values-clienttoolmode
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
CLIENT_TOOL_MODE_MIXED | 0 | Canonical | See meaning below. |
CLIENT_TOOL_MODE_BLOCK_ALL | 1 | Canonical | See meaning below. |
CLIENT_TOOL_MODE_MIXED
Record pending client tools and continue with server-executed MCP tools and the loop.
Do not wait on client tools; record pending and continue executing MCP tools and loop
CLIENT_TOOL_MODE_BLOCK_ALL
Hold loop advancement until the caller submits results for all pending client tools.
Block loop advancement until all client-side tool calls are resolved by the client
Values of failureMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#request-values-failuremode
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
FAILURE_MODE_CONTINUE | 0 | Canonical | Request continued processing after the failed tool call. |
FAILURE_MODE_STOP_LOOP | 1 | Canonical | Request stopping the current tool-execution loop after the failure. |
FAILURE_MODE_STOP_RUN | 2 | Canonical | Request stopping the generation run after the failure. |
In responses
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-requireapprovaltoolnamepatternsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-requireapprovaltoolnamepatternsrequireApprovalToolNamePatterns | Array of string | Optional | Tool-name patterns selecting calls that require an approval decision. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-requireapprovalserveridsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-requireapprovalserveridsrequireApprovalServerIds | Array of string | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-autoapprovetoolnamepatternsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-autoapprovetoolnamepatternsautoApproveToolNamePatterns | Array of string | Optional | Tool-name patterns whose matching calls may be approved automatically. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-autoapproveserveridsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-autoapproveserveridsautoApproveServerIds | Array of string | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-approvalmodeSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-approvalmodeapprovalMode | string (APPROVAL_MODE_MIXED, APPROVAL_MODE_BLOCK_ALL) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-clienttoolmodeSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-clienttoolmodeclientToolMode | string (CLIENT_TOOL_MODE_MIXED, CLIENT_TOOL_MODE_BLOCK_ALL) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-approvaltimeoutmsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-approvaltimeoutmsapprovalTimeoutMs | string (int64) | Optional | Time allowed for an approval decision, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait setting. At expiry, matching fail_on_approval_timeout_tool_name_patterns produces FAILED; other calls become TIMED_OUT. An empty pattern list makes every expiry FAILED. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-failonapprovaltimeouttoolnamepatternsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-failonapprovaltimeouttoolnamepatternsfailOnApprovalTimeoutToolNamePatterns | Array of string | Optional | Selects approval timeouts reported as FAILED; nonmatching calls become TIMED_OUT. An empty list makes every approval expiry FAILED. Global failure_mode is not enforced. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-orderrulesSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-orderrulesorderRules | Array of ToolExecutionOrderRule | Optional | Stored requested ordering rules; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-stablesortbycallindexontieSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-stablesortbycallindexontiestableSortByCallIndexOnTie | boolean | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-maxparalleltoolcallsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-maxparalleltoolcallsmaxParallelToolCalls | string (int64) | Optional | Maximum concurrent MCP tool executions. Zero, omission or one runs MCP calls sequentially; larger values permit concurrency. Client calls are armed separately, and their execution concurrency is controlled by the caller application. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-maxtoolcallsperloopSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-maxtoolcallsperloopmaxToolCallsPerLoop | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-maxtotaltoolcallsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-maxtotaltoolcallsmaxTotalToolCalls | string (int64) | Optional | Maximum admitted tool calls across the run; zero or omission leaves the cap unset. Client calls count when armed. Routable MCP calls count before approval, including calls later rejected. Unknown tools and calls refused by an exhausted cap do not count. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-retriabletoolnamepatternsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-retriabletoolnamepatternsretriableToolNamePatterns | Array of string | Optional | Stored requested retry selection; does not enable retries in the current workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-maxretriesSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-maxretriesmaxRetries | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-retrybackoffSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-retrybackoffretryBackoff | Backoff | Optional | Stored requested retry delays; not applied by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-retryableerrorsubstringsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-retryableerrorsubstringsretryableErrorSubstrings | Array of string | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-nonretryableerrorsubstringsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-nonretryableerrorsubstringsnonRetryableErrorSubstrings | Array of string | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-timeoutsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-timeoutstimeouts | TimeoutPolicy | Optional | Overall execution time budget for the generation run. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-clienttooltimeoutmsSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-clienttooltimeoutmsclientToolTimeoutMs | string (int64) | Optional | Time allowed for a client-side tool result, in milliseconds. Zero or omission selects the five-minute default; a positive value overrides it. There is no unbounded wait. The resolved answer deadline is returned as clientToolDeadlineAt on each call. A result arriving after the deadline is rejected. At expiry, an empty or matching fail_on_approval_timeout_tool_name_patterns list yields FAILED; other calls become TIMED_OUT. Expiry closes the answer window and does not cancel a client action already in progress. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-failuremodeSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-failuremodefailureMode | string (FAILURE_MODE_CONTINUE, FAILURE_MODE_STOP_LOOP, FAILURE_MODE_STOP_RUN) or integer (int32) | Optional; explicit presence | See meaning below. |
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#field-stoponfailurerulesSection ID: DOC-API-MODEL-schema-1h2ji21uc4#response-field-stoponfailurerulesstopOnFailureRules | Array of StopOnFailureRule | Optional | Stored requested stop rules; not evaluated by the current generation workflow. |
approvalMode
How to schedule execution when approvals are required for some tools
default: APPROVAL_MODE_MIXED
clientToolMode
Stored requested client-tool scheduling mode; not enforced by the current workflow.
default: CLIENT_TOOL_MODE_MIXED
maxToolCallsPerLoop
Stored requested per-loop tool-call cap; not enforced by the current generation workflow.
0 = no cap
maxRetries
Stored requested retry count; does not enable retries in the current workflow.
per tool-call
failureMode
Stored requested failure action; not enforced by the current generation workflow.
default if no rule matches
Values of approvalMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#response-values-approvalmode
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
APPROVAL_MODE_MIXED | 0 | Canonical | See meaning below. |
APPROVAL_MODE_BLOCK_ALL | 1 | Canonical | See meaning below. |
APPROVAL_MODE_MIXED
Run automatically approved calls immediately and hold only calls that require approval.
Run auto-approved tool calls immediately; hold only those requiring approval.
APPROVAL_MODE_BLOCK_ALL
Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected.
Block execution of all tool calls in the loop until all approval-required calls are approved/rejected.
Values of clientToolMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#response-values-clienttoolmode
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
CLIENT_TOOL_MODE_MIXED | 0 | Canonical | See meaning below. |
CLIENT_TOOL_MODE_BLOCK_ALL | 1 | Canonical | See meaning below. |
CLIENT_TOOL_MODE_MIXED
Record pending client tools and continue with server-executed MCP tools and the loop.
Do not wait on client tools; record pending and continue executing MCP tools and loop
CLIENT_TOOL_MODE_BLOCK_ALL
Hold loop advancement until the caller submits results for all pending client tools.
Block loop advancement until all client-side tool calls are resolved by the client
Values of failureMode
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#response-values-failuremode
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
FAILURE_MODE_CONTINUE | 0 | Canonical | Request continued processing after the failed tool call. |
FAILURE_MODE_STOP_LOOP | 1 | Canonical | Request stopping the current tool-execution loop after the failure. |
FAILURE_MODE_STOP_RUN | 2 | Canonical | Request stopping the generation run after the failure. |
Where used
Section ID: DOC-API-MODEL-schema-1h2ji21uc4#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| 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 |
| Update context management settings | POST /api/v1/llm/update-context-management-settings |
| Update default generation config | POST /api/v1/llm/update-default-generation-config |
| Update prompt variables | POST /api/v1/llm/update-prompt-variables |
| Update conversation settings | POST /api/v1/llm/update-settings |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| Append a message without generating | POST /api/v1/llm/append-message |
| Create a new conversation thread | POST /api/v1/llm/create-thread |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| ConversationSettings | Nested in model |
| ConversationSettings | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1h2ji21uc4