CCA-F start here · Trap gym · Which tool_choice?

Which tool_choice?

The trap: every option makes Claude more likely to call the right tool, and only one makes it certain at the right firmness. A prompt line, a retry in code, “any” and a forced tool all look like fixes. The exam wants the setting that matches the need: any tool at all, or one particular tool first.

D2 Tool Design & MCPD4 Prompt Engineering & Structured OutputExam guide 2.3 and 4.3About 12 minutes

At a glance: tool_choice set to “auto” lets Claude choose between text and a tool, “any” forces it to call some tool, and naming one tool forces that exact tool, for example to run extraction first.

Start here: the waiter's three phrases

A waiter can say three things to a guest.

“Whatever you like.” The guest may chat, ask a question or order. That is "auto": Claude may reply in text or call a tool.
“You must order something.” The guest has to pick a dish, but any dish. That is "any": Claude must call a tool, and picks which.
“You must start with the soup.” The first dish is fixed. That is a forced tool, {"type": "tool", "name": "…"}: Claude must call that exact tool.

tool_choice is a field on a Claude API request, sent next to the list of tools. It decides how firm the next move is. A tool_use response means Claude called a tool (the API's stop_reason is "tool_use"); a text response means it just wrote an answer (stop_reason is "end_turn"). A prompt line such as “always call the extraction tool first” is followed most of the time, not every time. The setting is what makes it certain.

One API request messages + tools + tool_choice "none" text only tools can't be called real API value, not in the guide "auto" text or any tool Claude decides may return text "any" must call a tool Claude picks which never plain text forced tool must call this one e.g. extract_metadata so it runs first looser: Claude decides more firmer: you decide more
The one question to ask: does the step need any tool call at all, or one particular tool to run first?

Words in the question that tell you which setting

Points to “auto”

  • may answer directly
  • a tool only when needed
  • a normal conversation

Points to “any”

  • must always return structured output, and there are several schemas to choose from
  • never reply with plain text
  • one of several schemas; the type is not known in advance
  • “when it calls a tool, it picks the right one”

Points to a forced tool

  • must run first, before any enrichment
  • always start with
  • a named tool such as extract_metadata
  • “sometimes it calls the other tool first”

Why “structured output” points to a tool at all: Claude returns structured output by calling a tool whose input schema is the shape you want, so “always return structured output” means “always call a tool”. That rules out “auto”, which may reply in text. Both “any” and a forced tool guarantee the call. The number of schemas decides between them: with several, Claude must choose, so use “any”; with only one, forcing that tool is just as good, and the exam usually signals forcing with order (“must run first”).

Try it: replay 200 requests

Pick a request, then pick its tool_choice. The simulator replays 200 requests of that kind, colours each one by what came back, and shows a sample response for each outcome. The diagram above highlights your setting.

1. The request

2. tool_choice

    
what the step neededa tool, but not the right moveno usable tool call

Sample responses

The rates are illustrative, chosen to show the shape. They are not measurements. The exam guide's point is that “auto” may return text, “any” guarantees a tool call but not which one, and a forced tool guarantees which one.

Things to try: Invoice pipeline + “auto”, then + “any”: the text replies vanish but some invoices still start with enrich_vendor. Then + forced extract_metadata. Then Unlabelled documents + forced to see forcing go wrong, and + “any”. Last, Support chat + “any”: a guarantee nobody wanted.

The four traps

TrapWhat the wrong option looks likeWhy it loses
Only usually worksAdd a line to the system prompt telling Claude to always call the extraction tool firstA prompt instruction is followed most of the time, not every time. tool_choice makes the first call certain.
Delays the problemLeave tool_choice on “auto” and check the reply in code, asking again when it comes back as textIt pays for a wasted call and a retry each time, when “any” would stop plain-text replies at the source.
Different problemSet tool_choice to “any” when one specific tool must run first“any” lets Claude pick which tool. Only forcing the named tool guarantees which one runs first.
OverbuiltRemove every tool except the extraction tool for the first request; or add a classify step, then force the matching extractor, when Claude already picks wellIt changes the tool set or adds a call per request. One setting does the same job.

Practice: three exam-style questions

Answer first, then open “Think it through”.

Rule to remember

Use “any” to guarantee a tool call, and a forced named tool to guarantee which one runs first. Leave “auto” for steps where text is a fine answer.

Exam guide 4.3: “tool_choice: "auto" (may return text), "any" (must call a tool), forced (specific named tool).” Exam guide 2.3: “Force a tool to run first (e.g., extract_metadata before enrichment); "any" guarantees a tool call rather than text.”

Footnote: on some of the newest Claude models, forced “any” and named-tool choices are no longer accepted, and the API recommends “auto” plus an instruction, strict tools or structured outputs instead. The exam tests the guide's version, which this page follows.

← All traps