ToolChoice
Policy selecting automatic tool choice, no tool use, or a named tool.
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 |
|---|---|---|---|
kind | string (TOOL_CHOICE_KIND_AUTO, TOOL_CHOICE_KIND_NONE, TOOL_CHOICE_KIND_SPECIFIC) or integer (int32) | Optional | Discriminator selecting the representation or policy used by this message. |
specificToolName | string | Optional | Only used when kind = TOOL_CHOICE_KIND_SPECIFIC. |
Values of kind
How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_CHOICE_KIND_AUTO | 1 | Canonical | Let the provider decide whether to call an available tool. |
TOOL_CHOICE_KIND_NONE | 2 | Canonical | Disable tool selection for this generation. |
TOOL_CHOICE_KIND_SPECIFIC | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
kind | string (TOOL_CHOICE_KIND_AUTO, TOOL_CHOICE_KIND_NONE, TOOL_CHOICE_KIND_SPECIFIC) or integer (int32) | Optional | Discriminator selecting the representation or policy used by this message. |
specificToolName | string | Optional | Only used when kind = TOOL_CHOICE_KIND_SPECIFIC. |
Values of kind
How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_CHOICE_KIND_AUTO | 1 | Canonical | Let the provider decide whether to call an available tool. |
TOOL_CHOICE_KIND_NONE | 2 | Canonical | Disable tool selection for this generation. |
TOOL_CHOICE_KIND_SPECIFIC | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
kind | string (TOOL_CHOICE_KIND_AUTO, TOOL_CHOICE_KIND_NONE, TOOL_CHOICE_KIND_SPECIFIC) or integer (int32) | Optional | Discriminator selecting the representation or policy used by this message. |
specific_tool_name | string | Optional | Only used when kind = TOOL_CHOICE_KIND_SPECIFIC. |
Values of kind
How the model provider should choose whether and which tool to call.
| Value | No. | Form | Meaning |
|---|---|---|---|
TOOL_CHOICE_KIND_AUTO | 1 | Canonical | Let the provider decide whether to call an available tool. |
TOOL_CHOICE_KIND_NONE | 2 | Canonical | Disable tool selection for this generation. |
TOOL_CHOICE_KIND_SPECIFIC | 3 | Canonical | Require the named tool specified by the enclosing tool-choice configuration. |
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 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 |
| 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). |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-tool-choice.