- In short
- tool_choice is the Messages API field that controls whether and how Claude calls a tool. It has four values: auto (the model decides), any (it must call some tool but picks which), tool (it must call one specific named tool), and none (no tools allowed).
What the Claude tool choice parameter is
The Claude tool_choice parameter is a single setting on a Messages API request that controls whether Claude is allowed to call a tool and, if so, how much freedom it has in choosing. It sits alongside your tools array, and changing it does not change what tools exist, only how the model is permitted to use them on that turn. Knowing the four values cold is a recall-level expectation on the Claude Certified Architect exam, because higher-level questions assume you already have them memorised.
There are exactly four values, and they form a spectrum from full model discretion to no tools at all. Memorise them as a ladder: auto gives the model the most freedom, any removes the option of answering in plain text, tool removes the choice of which tool, and none removes tools entirely.
- tool_choice
- A Messages API field controlling tool invocation. auto: the model decides whether to call a tool. any: it must call a tool but selects which. tool: it must call one named tool. none: it may not call any tool (the default when no tools are provided).
The four values, precisely
Each value answers a different question. auto answers "may the model use a tool?" with "yes, if it judges one is needed." The others tighten that contract.
auto. Claude decides on each turn whether to call any provided tool or to respond directly in text. This is the default whenever you supply atoolsarray, and it is the right setting for general conversational operation where a text answer is sometimes the correct output.any. Claude must use one of the provided tools, but it is not told which. Use this when a tool call is mandatory, for example you always want structured output, yet the appropriate tool depends on the input.tool(forced). Claude must call one specific tool that you name, expressed as a value of typetoolwith aname, such as{"type": "tool", "name": "get_weather"}. Use it to guarantee a particular action, like a mandatory first step.none. Claude may not call any tool. This is the default when notoolsare supplied, and you can set it explicitly to suppress tools on a turn without removing their definitions.
Reading the ladder in one pass
A fast way to lock the four values in memory is to read them as answers to two yes/no questions asked in order. Question one: must a tool be called on this turn? If no, you are choosing between auto (tools allowed but optional) and none (tools forbidden). If yes, ask question two: must it be one specific tool? If no, that is any; if yes, that is the forced tool form. Walking the ladder this way means you never have to recall the values in the abstract, you derive the right one from the requirement in front of you, which is exactly how the exam presents them.
Steering auto without forcing
Before reaching for any or tool, it helps to know that auto is far more controllable than it first appears, and that matters because forcing carries side effects the rest of this page details. Anthropic documents that the boundary auto draws, call a tool or answer directly, is steerable through the system prompt. A light instruction such as "Use the tools to investigate before responding" measurably increases how often Claude calls a tool. A stronger "Always call a tool first before responding" pushes the behaviour further. A conservative "Use your judgment about whether to call a tool or respond directly" keeps triggering restrained. None of these is a hard guarantee, that is precisely what any and tool exist to provide, but for many applications a nudged auto produces the behaviour you want while preserving the model's freedom to answer in plain text when that is genuinely the correct output. The architect's instinct is to reach for forcing only when a tool call must happen, not merely when you would prefer one.
How forcing changes the model's behaviour
The two forcing values, any and tool, do more than narrow the choice. Under the hood, the API prefills the assistant message so a tool call is guaranteed, and that has a visible consequence you must remember: the model will not emit a natural-language response or explanation before the tool_use block, even if you explicitly ask it to. If your UX depends on Claude narrating "I'll look that up for you" before acting, forcing removes that narration.
Anthropic's documented workaround is to keep tool_choice on auto and instead add a direct instruction in a user message, for example, "Use the get_weather tool in your response." That keeps natural language while still steering toward the tool. There is also an important compatibility rule: when you use extended thinking, only auto and none are supported. Setting any or tool together with extended thinking returns an error, because the forced prefill conflicts with the thinking block.
A detail that trips people up: caching and tokens
Two operational facts round out a complete mental model. First, the forcing values cost slightly more. Because the API injects extra instruction to compel a call, any and tool add more tool-use system-prompt tokens than auto or none on every request. The amounts are model-specific and small but real: Anthropic's published figures for Claude Opus 4.8 list 290 tool-use system-prompt tokens for auto or none against 410 for any or tool, and that gap, forcing always being the larger, recurs across every current model in the table. Second, tool_choice interacts with prompt caching, and the documentation is precise about how: changing the parameter invalidates cached message blocks, while your tool definitions and system prompt remain cached, so only the message content must be reprocessed. Neither fact changes which value is correct for a use case, but both are exactly the kind of detail the exam can hinge a distractor on, the wrong option that claims forcing is free, or that it busts the entire cache.
Worked example
A developer wants Claude to always greet the user in text before calling a tool, but has set tool_choice to any to guarantee a tool always runs. The greeting never appears.
The behaviour is expected, not a bug. With tool_choice set to any, the API prefills the assistant turn to force a tool call, so Claude skips straight to the tool_use block and never produces the leading text, no matter how the prompt is worded. The developer has asked for two things that any cannot deliver together: a guaranteed tool call and a guaranteed natural-language preamble.
The fix follows directly from how the values are defined. Switch tool_choice back to auto, which permits text, and add an explicit instruction in the user message telling Claude to use the tool. Auto plus a clear instruction recovers the greeting while still reliably steering to the tool. If a hard guarantee of a tool call is non-negotiable and the preamble is merely nice to have, the developer instead keeps any and drops the greeting requirement, you cannot have both at once. Recognising that this is a definitional constraint, not a prompting failure, is the whole lesson.
Guaranteeing schema-valid calls with strict tools
Forcing a tool guarantees that a tool runs, but on its own it does not guarantee the arguments are well-formed. Anthropic pairs tool_choice with a separate feature, strict tool use, for that second guarantee. Setting strict: true on a tool definition constrains the model's output so the tool inputs always match your JSON schema exactly, rejecting malformed or hallucinated arguments at the grammar level rather than after the fact. Combining tool_choice of any with strict: true therefore gives you both promises at once: one of your tools will be called, and the input it is called with will validate against the schema. For an endpoint whose entire contract is to return a parsed, schema-conformant object, that pairing is the precise tool for the job. The detail worth carrying is that the two settings solve different halves of one problem, tool_choice governs whether and which tool, strict governs the shape of its inputs, so they compose rather than compete.
A second scenario: forcing a mandatory first step
The other place forcing genuinely earns its keep is when a specific action must always come first, regardless of what the user said.
Worked example
A support agent must always log an incident with a record_ticket tool at the very start of every conversation, before doing anything else, so that no request goes untracked.
Here the requirement is not "call some tool" but "call this exact tool, first." That is the textbook case for the forced tool form: set tool_choice to a value of type tool naming record_ticket, and the model must call exactly that tool on the opening turn. auto would be wrong because the model might judge a friendly greeting sufficient and skip the logging entirely; any would be wrong because the agent has several other tools and could satisfy "call a tool" by reaching for one of them while still logging nothing.
Now accept the trade-off forcing brings. On that first turn the agent cannot emit a natural-language greeting before the tool_use block, because the API prefills the assistant message to compel the call. If a greeting matters to the experience, you recover it on the very next turn: once the ticket is recorded, you switch tool_choice back to auto for the remainder of the conversation, where text and judgement are welcome again. The lesson that generalises is that tool_choice is a per-turn setting, not a global mode. You can compel the mandatory first step and then hand control straight back to the model, which is how production agents reconcile a hard guarantee with a conversational feel.
Misreadings the exam punishes
Misconception
tool_choice any and auto are basically the same; both let the model use tools.
What's actually true
Misconception
Forcing a tool with the type tool value still lets Claude explain itself in text first.
What's actually true
How this is tested
This knowledge point is assessed at the remember level of Bloom's taxonomy under task statement 2.3, which means the exam expects the four values and their behaviour to be instantly available and then makes you apply them in a single-step scenario. Two distractor traps are called out directly in the source material. The first is using auto when structured output is actually required: because auto lets Claude answer in plain text, an endpoint that must receive a tool call can silently get prose back instead, breaking the parser downstream. The second is confusing any with auto, treating the optional case as though it were guaranteed. Both traps disappear if you run the two-question ladder rather than relying on a vague memory of the names. The questions reward precision over familiarity: knowing that any removes the text escape hatch, that the forced tool form removes the choice of which tool, and that none removes tools while leaving their definitions in place is what separates a confident answer from a coin flip.
Where this sits in the bigger picture
These four values are the vocabulary for everything that follows. The tool description is what makes auto and any choose well, which is why it is a prerequisite here. Once you know what each setting does, the applied question, which setting to reach for in a given scenario, is covered in tool_choice application scenarios, and the deeper semantics of how forcing shapes output appear in tool_choice semantics. Memorise the ladder here, and those evaluation-level pages have a solid base to build on.
You are building an endpoint that must always return a parsed result by calling one of three extraction tools, but you do not know in advance which document type, and therefore which tool, applies. Which tool_choice value fits?
People also ask
What is the difference between tool_choice auto and any?
How do you force Claude to use a specific tool?
What does tool_choice none do?
Does tool_choice any let the model choose which tool?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Fine grained tool calling
Why watch: Controlling whether and which tool fires maps directly to the auto/any/forced tool_choice settings this KP covers.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.