When you pass tool definitions in a Messages API request, the tool_choice parameter controls who picks the next move. There are four values (the classic three, plus none):
| Value | Behavior |
|---|---|
{"type": "auto"} | Claude decides whether to use tools — the default when tools are present |
{"type": "any"} | Claude must use at least one tool, but chooses which |
{"type": "tool", "name": "..."} | Claude must call the named tool |
{"type": "none"} | Claude cannot use tools, even though definitions were sent |
Any of these can additionally set "disable_parallel_tool_use": true, which caps the response at a single tool call. Parallel calls — several tool_use blocks in one response — are allowed by default, and turning them off matters for tools with side effects where ordering is significant.
The workhorse pattern: forcing one tool for structured extraction
Forcing a specific tool turns a free-text model into a predictable pipeline component. Define a tool whose input schema is your desired output shape, force it with tool_choice, and read the arguments from the tool_use block — the "tool" never needs a real implementation. Add "strict": true to the definition and the API guarantees the tool name and input conform to your schema exactly.
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")
resp = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=[{
"name": "record_ticket",
"description": "Record a classified support ticket.",
"input_schema": {"type": "object", "properties": {
"category": {"type": "string"},
"urgent": {"type": "boolean"}}},
"strict": True,
}],
tool_choice={"type": "tool", "name": "record_ticket"},
messages=[{"role": "user", "content": "Ticket: 'Site is down!!'"}],
)
For pure output formatting (no tool semantics at all), structured outputs via output_config.format achieves the same schema guarantee without the tool scaffolding; the forced-tool pattern earns its place when you want the model to choose values for a downstream action, or when several candidate tools exist and you occasionally force one.
When to use each mode
auto is for genuine agents and assistants: the model may answer directly or reach for a tool, and either is acceptable. any fits routing layers — you expose several handler tools ("create_ticket", "escalate", "answer_faq") and require that the model commit to one of them rather than replying in prose; which one is still its judgment call. tool is for fixed workflow steps like the extraction pattern above. none is for turns inside a tool-enabled conversation where you want a plain-text summary without another tool round-trip.
Constraints and costs worth knowing
Extended thinking is incompatible with forcing. With thinking active, only auto and none are supported — any and tool return an error. If a pipeline step needs a forced tool call, run that step without thinking.
Forcing costs slightly more system-prompt overhead. Tool use adds a hidden system prompt whose size depends on the mode: on Opus 4.8 it is 290 tokens for auto/none versus 410 for any/tool; on Sonnet 5, 354 versus 474. Small numbers, but they compound at volume. With tool_choice: none and no tools provided at all, the overhead is zero.
Changing tool_choice invalidates the message-level prompt cache (tool definitions and system prompt stay cached). A pipeline that flips between modes per request will see lower cache hit rates on conversation history than one that keeps the mode stable.
Cache pre-warming doesn't mix with forcing. The max_tokens: 0 pre-warm request is rejected when tool_choice is tool or any.
auto and let the model exercise judgment; reach for any when a response must be machine-actionable; reserve tool for single-purpose extraction and fixed workflow steps — and pair it with strict: true so the schema guarantee is absolute.Platform notes
Tool use, including tool_choice, is core Messages API functionality available on all four third-party platforms — Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry — alongside the first-party API. Structured outputs and strict tool use are GA on all platforms except Foundry, where they are in beta.
Where to go next
Continue with strict tool use, parallel tool calls, and handling tool result errors; the classification angle is covered in classification prompting patterns.