- In short
- Claude tool choice is the tool_choice request parameter that decides whether and how the model must use the tools you supplied. auto lets Claude reply with plain text or a tool call, any forces it to call one of the tools but lets it pick which, and a named tool forces a specific tool every time, which is how you guarantee a structured response.
What the Claude tool choice parameter does
The Claude tool_choice parameter answers a different question from the schema. A tool's input_schema decides what a tool call must look like; tool_choice decides whether Claude is allowed to skip the call altogether. Conflating the two is the root of most structured-output surprises, so it is worth holding them apart from the start. You can have a flawless extraction schema and still receive a paragraph of prose, simply because nothing in the request obliged the model to use the tool.
The official documentation lists four settings, and three of them carry the weight for Task 4.3. The setting you do not pass is itself a decision: when you supply tools without specifying tool_choice, the model runs in auto, free to decide that a plain text answer is the better response. For a conversational assistant that is exactly right. For a data-extraction endpoint that must always return a record, it is a latent bug.
- Claude tool choice
- The tool_choice request parameter governing tool usage. auto permits a text reply or a tool call, any forces a tool call while letting the model choose the tool, a named tool forces one specific tool, and none disables tools. It controls mandatory-ness, not output shape.
The three settings that matter for extraction
Think of the settings as a dial from most freedom to least. auto gives Claude full discretion: answer in text, or call any tool it judges helpful. It is the default whenever tools are present and the correct choice for agents that sometimes reason aloud and sometimes act.
any removes the option of a text-only answer. The model must call one of the tools you provided, but it still chooses which. This is the setting for guaranteed structured output when several tools could apply, for example a router that picks among extract_invoice, extract_receipt, and extract_statement depending on an unknown document type. You are guaranteed a structured call without prejudging which extractor fits.
A named tool, written as a tool_choice of type tool with a specific name, forces that one tool every time. This is how you make a step mandatory: if every document in a batch must be processed by extract_record first, naming the tool removes the model's freedom to do anything else. The fourth option, none, simply forbids tools and is the default when no tools are supplied; it rarely appears in extraction design.
How the Claude tool choice setting guarantees structured output
The connection to structured output is direct. A schema cannot help you if the model never calls the tool, so guaranteeing a structured response is a two-part move: define the schema, then use tool_choice to make the call non-optional. Choose any when any of several tools would produce an acceptable record, and a named tool when exactly one should run.
There is a behavioural subtlety the exam likes to probe. When tool_choice is any or a named tool, the API prefills the assistant message to force a tool to be used, which means the model will not emit a natural-language preface or visible reasoning before the tool_use block, even if you ask it to. That is usually what you want for a clean machine-readable result, but if you specifically need Claude to narrate its reasoning and still call a tool, you must stay on auto and request the tool in the user message instead. Knowing that forcing a tool silences the preamble is a frequently tested detail.
A pipeline that returned prose, and the one-line fix
Worked example
An ingestion service sends each uploaded contract to Claude with an extract_terms tool, expecting JSON back. Intermittently it stores a chatty paragraph instead of a record, and the database write fails.
The team is convinced the schema is broken, because most calls succeed and a minority return text. They tighten the tool description, add an example, and the intermittent prose persists. The schema was never the problem. Because no tool_choice was set, the request ran in auto, and on documents the model found ambiguous or conversational it judged a written explanation to be the more helpful reply, which auto explicitly permits.
The correct fix is a single parameter. Because exactly one extractor should always run, they set tool_choice to the named extract_terms tool. From then on every call returns a tool_use block, the text-only branch disappears, and the database writes stop failing. As a side effect the model also stops prefacing its answer with a sentence of commentary, because forcing a tool suppresses the leading text; the team had been stripping that commentary downstream and can now delete that code.
Had several contract types each needed a different extractor, the right call would have been any rather than a named tool, letting Claude select the matching extractor while still guaranteeing some structured call. The lesson is that the cure for prose-when-you-wanted-JSON is almost never a bigger prompt; it is the tool_choice setting that makes the call mandatory.
Common misconceptions to avoid
Misconception
My extraction tool has a strict schema, so Claude will always return structured JSON.
What's actually true
Misconception
Using any and forcing a specific named tool are interchangeable ways to guarantee structured output.
What's actually true
The hidden cost of leaving tool_choice on auto
The default is comfortable precisely because it rarely fails loudly. An endpoint left on auto returns clean JSON on the overwhelming majority of inputs, so it passes a casual test and ships. The cost is paid later and intermittently, on the minority of documents where the model judges a written explanation more helpful, and those are often the very documents that are ambiguous or unusual, which is to say the ones a human most needs captured. A failure rate of a few percent is invisible in a demo and corrosive in production, because it concentrates exactly where the data matters most.
This is why experienced architects treat the absence of a tool_choice setting as a smell on any endpoint whose contract is always return a record. The question to ask is not does it usually return JSON but is it structurally impossible for it to return prose. Only any or a named tool make that guarantee, and the difference between usually and always is the difference between a pipeline you can build on and one that quietly drops its hardest cases.
Where none fits, and the full four-way picture
For completeness it is worth placing the fourth setting. none forbids tools entirely and is the implicit default whenever you supply no tools at all; you reach for it explicitly only when you have tools defined but want to suppress them for a particular turn, perhaps to get a plain conversational reply mid-conversation. In an extraction pipeline it almost never appears, but knowing it exists keeps the model of tool_choice complete: a spectrum running from forbidden, through optional, to mandatory-but-free, to mandatory-and-fixed.
A caching subtlety worth remembering
There is an operational detail the documentation flags that can trip up high-volume pipelines. When you use prompt caching, changing the tool_choice parameter invalidates the cached message blocks, even though tool definitions and system prompts stay cached. If you are dynamically switching between auto and a forced tool across requests to save cost, you may be quietly defeating part of your cache and paying to reprocess message content. It rarely changes the correct setting for a given endpoint, but it is the kind of second-order consequence worth knowing, because it shows you understand tool_choice as a real parameter with real system effects rather than a toggle in a tutorial.
Forcing a tool changes the response shape
Because forcing a tool prefills the assistant turn, the response you get back is shaped differently from an auto response, and your downstream code should expect that. Under auto the model often emits a friendly text block before the tool call, narrating what it is about to do, and your parser has to skip that block to find the structured data. Under any or a named tool that narration disappears, so the first content block is the tool use itself. Teams that switch from auto to a forced tool sometimes find their block-walking code was implicitly relying on a leading text block and can now be simplified, which is a small but real migration consideration.
Why prompting cannot substitute for the setting
A recurring temptation is to keep auto and simply instruct the model, in capital letters if necessary, that it must always use the tool. This works most of the time and is therefore seductive, but most of the time is exactly the standard a guaranteed contract is meant to exceed. The parameter is enforced by the API; the instruction is a request the model can decline when it judges a text answer better. The whole reason tool_choice exists as a parameter rather than a prompting convention is that some requirements need a hard guarantee, and recognising when a requirement has crossed into that territory is the judgement being assessed. State the requirement in one plain sentence first, decide whether the structured call is genuinely mandatory, and let that decision pick the setting for you.
Pairing tool_choice with strict tool use
tool_choice and schema strictness answer two different halves of the same guarantee, and the strongest extraction endpoints set both. A tool_choice of any or a named tool guarantees that a tool call happens at all; strict: true on the tool definition guarantees that when the call happens, its inputs are validated against the schema rather than merely shaped by it. Anthropic recommends combining tool_choice of type any with strict: true precisely when you need both promises at once: a call you can count on, carrying arguments you can count on.
Holding the two apart explains a class of confusing results. If you force a tool but leave the schema non-strict, you are guaranteed a tool_use block, yet a subtle argument-level violation can still slip through on a model that was only loosely shaped. If you set the schema strict but leave tool_choice on auto, the validation is real but may never run, because the model is still free to answer in prose. The complete contract is the conjunction: make the call mandatory with tool_choice, and make the inputs trustworthy with strict: true.
How it shows up on the exam
Within Domain 4, the structured-output task is tested most directly through Scenario 6, and tool_choice questions tend to wear a recognisable costume: a pipeline that returns text some of the time when the architect expected JSON every time. The distractors will tempt you toward prompt engineering, lower temperature, or a schema rewrite, but the controlling fact is that auto permits a text reply. The credited answer sets tool_choice to any when several tools could apply or to a specific named tool when one must always run. A second style of question rewards the detail that forcing a tool suppresses any leading explanation, so watch for stems where the requirement is structured output without preamble. Match the symptom to the setting and the noise falls away.
A document-processing service must return a structured record for every file, but the files arrive as invoices, receipts, or bank statements, and each has its own extraction tool. Calls currently use the default and sometimes return prose. Which tool_choice configuration best fits the requirement?
People also ask
What are the tool_choice options in the Claude API?
Why is Claude returning text instead of calling my tool?
Does forcing a tool stop Claude from explaining itself first?
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: The same tool_choice semantics guarantee structured output is produced when you need it for extraction.
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.