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.
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 |
|---|---|---|---|
requireApprovalToolNamePatterns | Array of string | Optional | Approvals Tool-name patterns selecting calls that require an approval decision. |
requireApprovalServerIds | Array of string | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. |
autoApproveToolNamePatterns | Array of string | Optional | Tool-name patterns whose matching calls may be approved automatically. |
autoApproveServerIds | Array of string | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. |
approvalMode | string (APPROVAL_MODE_MIXED, APPROVAL_MODE_BLOCK_ALL) or integer (int32) | Optional | How to schedule execution when approvals are required for some tools |
clientToolMode | string (CLIENT_TOOL_MODE_MIXED, CLIENT_TOOL_MODE_BLOCK_ALL) or integer (int32) | Optional | Stored requested client-tool scheduling mode; not enforced by the current workflow. |
approvalTimeoutMs | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
failOnApprovalTimeoutToolNamePatterns | 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. |
orderRules | Array of ToolExecutionOrderRule | Optional | Stored requested ordering rules; not applied by the current generation workflow. |
stableSortByCallIndexOnTie | boolean | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. |
maxParallelToolCalls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
maxToolCallsPerLoop | integer (int32) | Optional | Stored requested per-loop tool-call cap; not enforced by the current generation workflow. Minimum: -2147483648. Maximum: 2147483647. |
maxTotalToolCalls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
retriableToolNamePatterns | Array of string | Optional | Stored requested retry selection; does not enable retries in the current workflow. |
maxRetries | integer (int32) | Optional | Stored requested retry count; does not enable retries in the current workflow. Minimum: -2147483648. Maximum: 2147483647. |
retryBackoff | Backoff | Optional | Stored requested retry delays; not applied by the current generation workflow. |
retryableErrorSubstrings | Array of string | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. |
nonRetryableErrorSubstrings | Array of string | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. |
timeouts | TimeoutPolicy | Optional | Timeouts Overall execution time budget for the generation run. |
clientToolTimeoutMs | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
failureMode | string (FAILURE_MODE_CONTINUE, FAILURE_MODE_STOP_LOOP, FAILURE_MODE_STOP_RUN) or integer (int32) | Optional | Stored requested failure action; not enforced by the current generation workflow. |
stopOnFailureRules | Array of StopOnFailureRule | Optional | Stored requested stop rules; not evaluated by the current generation workflow. |
Values of approvalMode
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
APPROVAL_MODE_MIXED | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
APPROVAL_MODE_BLOCK_ALL | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Values of clientToolMode
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
CLIENT_TOOL_MODE_MIXED | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
CLIENT_TOOL_MODE_BLOCK_ALL | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Values of failureMode
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
FAILURE_MODE_CONTINUE | 1 | Canonical | Request continued processing after the failed tool call. |
FAILURE_MODE_STOP_LOOP | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
FAILURE_MODE_STOP_RUN | 3 | Canonical | Request stopping the generation run after the failure. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
requireApprovalToolNamePatterns | Array of string | Optional | Approvals Tool-name patterns selecting calls that require an approval decision. |
requireApprovalServerIds | Array of string | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. |
autoApproveToolNamePatterns | Array of string | Optional | Tool-name patterns whose matching calls may be approved automatically. |
autoApproveServerIds | Array of string | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. |
approvalMode | string (APPROVAL_MODE_MIXED, APPROVAL_MODE_BLOCK_ALL) or integer (int32) | Optional | How to schedule execution when approvals are required for some tools |
clientToolMode | string (CLIENT_TOOL_MODE_MIXED, CLIENT_TOOL_MODE_BLOCK_ALL) or integer (int32) | Optional | Stored requested client-tool scheduling mode; not enforced by the current workflow. |
approvalTimeoutMs | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
failOnApprovalTimeoutToolNamePatterns | 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. |
orderRules | Array of ToolExecutionOrderRule | Optional | Stored requested ordering rules; not applied by the current generation workflow. |
stableSortByCallIndexOnTie | boolean | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. |
maxParallelToolCalls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
maxToolCallsPerLoop | integer (int32) | Optional | Stored requested per-loop tool-call cap; not enforced by the current generation workflow. Minimum: -2147483648. Maximum: 2147483647. |
maxTotalToolCalls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
retriableToolNamePatterns | Array of string | Optional | Stored requested retry selection; does not enable retries in the current workflow. |
maxRetries | integer (int32) | Optional | Stored requested retry count; does not enable retries in the current workflow. Minimum: -2147483648. Maximum: 2147483647. |
retryBackoff | Backoff | Optional | Stored requested retry delays; not applied by the current generation workflow. |
retryableErrorSubstrings | Array of string | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. |
nonRetryableErrorSubstrings | Array of string | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. |
timeouts | TimeoutPolicy | Optional | Timeouts Overall execution time budget for the generation run. |
clientToolTimeoutMs | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
failureMode | string (FAILURE_MODE_CONTINUE, FAILURE_MODE_STOP_LOOP, FAILURE_MODE_STOP_RUN) or integer (int32) | Optional | Stored requested failure action; not enforced by the current generation workflow. |
stopOnFailureRules | Array of StopOnFailureRule | Optional | Stored requested stop rules; not evaluated by the current generation workflow. |
Values of approvalMode
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
APPROVAL_MODE_MIXED | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
APPROVAL_MODE_BLOCK_ALL | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Values of clientToolMode
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
CLIENT_TOOL_MODE_MIXED | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
CLIENT_TOOL_MODE_BLOCK_ALL | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Values of failureMode
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
FAILURE_MODE_CONTINUE | 1 | Canonical | Request continued processing after the failed tool call. |
FAILURE_MODE_STOP_LOOP | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
FAILURE_MODE_STOP_RUN | 3 | Canonical | Request stopping the generation run after the failure. |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
require_approval_tool_name_patterns | Array of string | Optional | Approvals Tool-name patterns selecting calls that require an approval decision. |
require_approval_server_ids | Array of string | Optional | MCP server identifiers whose calls require approval. IDs are compared case-insensitively after trimming whitespace. |
auto_approve_tool_name_patterns | Array of string | Optional | Tool-name patterns whose matching calls may be approved automatically. |
auto_approve_server_ids | Array of string | Optional | MCP server identifiers exempted from approval require rules. IDs are compared case-insensitively after trimming whitespace. |
approval_mode | string (APPROVAL_MODE_MIXED, APPROVAL_MODE_BLOCK_ALL) or integer (int32) | Optional | How to schedule execution when approvals are required for some tools |
client_tool_mode | string (CLIENT_TOOL_MODE_MIXED, CLIENT_TOOL_MODE_BLOCK_ALL) or integer (int32) | Optional | Stored requested client-tool scheduling mode; not enforced by the current workflow. |
approval_timeout_ms | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
fail_on_approval_timeout_tool_name_patterns | 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. |
order_rules | Array of ToolExecutionOrderRule | Optional | Stored requested ordering rules; not applied by the current generation workflow. |
stable_sort_by_call_index_on_tie | boolean | Optional | Stored requested ordering tie-breaker; not applied by the current generation workflow. |
max_parallel_tool_calls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
max_tool_calls_per_loop | integer (int32) | Optional | Stored requested per-loop tool-call cap; not enforced by the current generation workflow. Minimum: -2147483648. Maximum: 2147483647. |
max_total_tool_calls | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
retriable_tool_name_patterns | Array of string | Optional | Stored requested retry selection; does not enable retries in the current workflow. |
max_retries | integer (int32) | Optional | Stored requested retry count; does not enable retries in the current workflow. Minimum: -2147483648. Maximum: 2147483647. |
retry_backoff | Backoff | Optional | Stored requested retry delays; not applied by the current generation workflow. |
retryable_error_substrings | Array of string | Optional | Stored requested retryable-error selection; not evaluated by the current workflow. |
non_retryable_error_substrings | Array of string | Optional | Stored requested retry exclusions; not evaluated by the current generation workflow. |
timeouts | TimeoutPolicy | Optional | Timeouts Overall execution time budget for the generation run. |
client_tool_timeout_ms | integer (int32) | 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. Minimum: -2147483648. Maximum: 2147483647. |
failure_mode | string (FAILURE_MODE_CONTINUE, FAILURE_MODE_STOP_LOOP, FAILURE_MODE_STOP_RUN) or integer (int32) | Optional | Stored requested failure action; not enforced by the current generation workflow. |
stop_on_failure_rules | Array of StopOnFailureRule | Optional | Stored requested stop rules; not evaluated by the current generation workflow. |
Values of approval_mode
How approval-required tool calls affect other tool calls in the same execution loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
APPROVAL_MODE_MIXED | 1 | Canonical | Run automatically approved calls immediately and hold only calls that require approval. |
APPROVAL_MODE_BLOCK_ALL | 2 | Canonical | Hold execution of all tool calls in the loop until the approval-required calls are approved or rejected. |
Values of client_tool_mode
How unresolved caller-executed tools affect progression of the tool loop.
| Value | No. | Form | Meaning |
|---|---|---|---|
CLIENT_TOOL_MODE_MIXED | 1 | Canonical | Record pending client tools and continue with server-executed MCP tools and the loop. |
CLIENT_TOOL_MODE_BLOCK_ALL | 2 | Canonical | Hold loop advancement until the caller submits results for all pending client tools. |
Values of failure_mode
Requested scope of stopping after a tool execution failure.
| Value | No. | Form | Meaning |
|---|---|---|---|
FAILURE_MODE_CONTINUE | 1 | Canonical | Request continued processing after the failed tool call. |
FAILURE_MODE_STOP_LOOP | 2 | Canonical | Request stopping the current tool-execution loop after the failure. |
FAILURE_MODE_STOP_RUN | 3 | Canonical | Request stopping the generation run after the failure. |
Where used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| 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 |
| Send a message and wait for the result | POST /api/v1/llm/send-message-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 conversation settings | POST /api/v1/llm/update-settings |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| List agent profiles | POST /api/v1/agent-profiles/list |
| 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 |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| Update prompt variables | POST /api/v1/llm/update-prompt-variables |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| Generation configuration | API JSON uses JSON field names (camelCase). |
| llm.generation_started | Webhook JSON uses protobuf field names (snake_case). |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| ConversationSettings | Nested in model |
| ConversationSettings | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-tool-execution-policy.