Configuring tool_choice: auto, any, and Forced Tools

1.The four tool_choice values

Tool scoping decides which tools an agent has. tool_choice decides whether it must call one on a given request. By default, Claude decides for itself: with the default tool_choice of auto, Claude determines on each turn whether to call a tool or respond directly. You can push that decision with the system prompt. For example, "Always call a tool first before responding." makes tool calls more likely. A prompt still only influences the choice, though. The documentation is explicit: to require a tool call rather than rely on prompting, set tool_choice.

Older material, including the tool_choice cookbook, describes only three options: auto, tool and any. The current API reference lists four, adding none. none is also the default when a request includes no tools.

Sources12

2.Forcing a specific tool first

Use forced selection when one step has to happen before anything else. The API reference describes the case: you may want Claude to use a specific tool to answer the user's question, even if Claude would otherwise answer directly without calling a tool. You set it per request, in the tool_choice field.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

The exam guide's pipeline example is to force extract_metadata on the first request, so metadata exists before any enrichment tool runs, and then handle the later steps in follow-up turns. The documentation doesn't spell out this multi-turn recipe. It follows from two documented facts. First, tool_choice is set on each request. Second, type tool forces Claude to always use a particular tool. If you left the force in place, every turn would call extract_metadata again. So you force it once, return its tool_result, and send the follow-up request with auto so Claude can pick the enrichment tools that fit.

This is how forcing works internally: when you have tool_choice as any or tool, the API prefills the assistant message to force a tool to be used. If you need a written explanation as well, ask for it in a later turn or put it in the tool's inputs. Don't expect text before a forced tool call.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": " ? ", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

Sources2

3.Guaranteeing a tool call with any, and where forcing fails

With auto, Claude can get it wrong in either direction. The cookbook notes that Claude can be over-eager to call tools. In its sentiment example, a weak prompt with auto led to the opposite: Claude does not call our sentiment analysis tool and replies with chat text instead. When every response has to be a tool call, but the right tool depends on the input, use any. The cookbook's SMS assistant has two tools, send_text_to_user and get_customer_info. Its goal is a chatbot that always calls one of these tools and never responds with a non-tool response. Even when Claude needs to ask the user something, such as their username, it asks by calling send_text_to_user. It doesn't reply with plain text.

Forcing doesn't work everywhere. On settings or models that don't support it, any and tool fail. auto and none still work. Any architecture that depends on any or tool must check these limits first.

On those models, the documented alternative is auto with strict tool use to guarantee schema-valid tool inputs, together with prompting, which still influences which tool auto picks. Adaptive thinking on its own doesn't block forced tool use. The error comes from manual extended thinking, or from the listed models whatever their thinking settings.

Sources23

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.With tool_choice any or tool, Claude can still write a short explanation before the tool call if the prompt asks for one.Why is that wrong?

   The API prefills the assistant turn to force the tool call, so no text appears before the tool_use block.

   Covered in Forcing a specific tool first

2. 2.tool_choice any works with every configuration, including manual extended thinking.Why is that wrong?

   Under manual extended thinking, any and tool cause an error, and some current models reject them with a 400. Use auto or none in those cases.

   Covered in Guaranteeing a tool call with any, and where forcing fails