tool_choice: 4 Recipes That Ship (2026)

Quick Answer

tool_choice decides whether a model is allowed to call a tool, forced to, or forbidden. There are four modes and they are the same idea across vendors. On Claude: auto (the model decides, the default when tools are present), any (must call some tool), tool (must call one named tool), none (no tools). Anthropic documents all four in its tool use guide. OpenAI uses the same shape with different words: auto, required, none, and a forced named function. Four copy-paste recipes below, each with the failure mode that bites.

The mode is not a hint in your prompt. "Please call the tool" is a suggestion the model can skip. tool_choice is enforced by the decoder. Set it wrong and you either get chatter where you wanted a clean tool call, or a locked agent that can never answer. OpenAI's function-calling guide (2026) maps required to Claude's any; the rest line up one to one.

The four modes in one table

Recipe 1: force any tool

Claim: when the turn must end in an action, stop asking nicely and set any.

{
  "model": "claude-haiku-4-5",
  "tools": [{ "name": "log_ticket", "description": "File a support ticket", "input_schema": {"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]} }],
  "tool_choice": { "type": "any" },
  "messages": [{ "role": "user", "content": "The checkout page 500s on mobile Safari." }]
}

Receipt: the response comes back as a tool_use block, no chat. OpenAI equivalent: "tool_choice": "required".

Why it works: any prefills the assistant turn to a tool call, so the decoder cannot open with prose.

Failure mode: it also kills the preamble. The model will not explain itself first, even if you ask. Need reasoning plus a call? See Recipe 4.

Ship it when the only valid output is a tool call.

Recipe 2: pin one specific tool

Claim: for extraction and classification, name the tool. Do not let the model choose.

{
  "model": "claude-haiku-4-5",
  "tools": [{ "name": "extract_invoice", "description": "Pull fields from an invoice", "input_schema": {"type":"object","properties":{"total":{"type":"number"},"due_date":{"type":"string"}},"required":["total"]} }],
  "tool_choice": { "type": "tool", "name": "extract_invoice" },
  "messages": [{ "role": "user", "content": "Invoice 4471, total 1290.00 EUR, due Sept 30." }]
}

Receipt: one tool_use block for extract_invoice, arguments matching your schema. OpenAI: {"type":"function","name":"extract_invoice"}.

Why it works: this is the clean way to get typed, schema-shaped output without prompt-wrangling a JSON blob. Pair it with strict: true on Claude and the arguments are guaranteed to validate against your schema.

Failure mode: pinning a tool is not the same as forcing valid JSON in a text turn. If you want raw JSON in the message body instead, that is a different pattern; see our structured output recipes.

Ship it for single-purpose extractors and routers.

Recipe 3: forbid tools for one turn

Claim: in an agent loop, the closing turn should be text. Set none so the model writes the answer instead of calling one more tool.

{
  "model": "claude-haiku-4-5",
  "tools": [{ "name": "search", "description": "Search the docs", "input_schema": {"type":"object","properties":{"q":{"type":"string"}},"required":["q"]} }],
  "tool_choice": { "type": "none" },
  "messages": [
    { "role": "user", "content": "Summarize what you found." }
  ]
}

Receipt: a plain text turn. The tools are still declared, so the model stays aware of them, but it cannot call one. OpenAI: "tool_choice": "none".

Why it works: none lets you keep the tool definitions in context (and cached) while blocking calls for exactly one step.

Failure mode: people reach for none to save tokens. It does not drop the tool definitions from the prompt; they still cost input tokens. It only blocks the call.

Ship it on the final synthesis turn of a loop.

Recipe 4: leave it on auto, and keep the preamble

Claim: most of the time, do nothing. auto is the default and it is usually right.

{
  "model": "claude-haiku-4-5",
  "tools": [ /* your tools */ ],
  "tool_choice": { "type": "auto" },
  "messages": [{ "role": "user", "content": "What is the weather in Lisbon? Use the get_weather tool in your response." }]
}

Receipt: the model can open with a short natural-language line ("I'll check that for you.") and then emit the tool_use block. That preamble is what any and tool destroy.

Why it works: auto does not prefill the assistant turn, so reasoning text is allowed. If you need the model to call a specific tool AND talk, use auto and just ask for the tool by name in the user message. This is Anthropic's documented workaround for the no-preamble problem.

Failure mode: on ambiguous prompts auto will sometimes answer from memory instead of calling the tool. If the call is mandatory, that is Recipe 1's job, not auto's.

Ship it as the default. Only override when the output contract demands it.

Three failure modes that bite

Forcing a tool erases the preamble. any and tool prefill the assistant message, so there is no explanation before the tool_use block, even if your system prompt begs for one. If you need both, use auto plus an explicit instruction.

Forced tool use breaks manual extended thinking on Claude. With thinking: {type: "enabled"} set manually, any and tool return an error; only auto and none are allowed. Adaptive thinking, including models where thinking is on by default, does support forced tool use. This is the trap that turns up as a question devs keep re-asking (2025-2026): how do I get reasoning and a guaranteed call at once. On Claude with manual thinking, you cannot force it; you steer with auto.

Flipping tool_choice mid-conversation busts your prompt cache. On Claude, a change to tool_choice invalidates cached message blocks; tool definitions and the system prompt stay cached, but the message content is reprocessed. If you toggle modes every turn, you are paying full input price every turn.

When NOT to force a tool

Do not set any or required on every turn of an agent loop. If the model must call a tool at each step, it can never emit a final answer and the loop runs until your max-iterations cap. Force on the acting turns; switch to auto or none on the answering turn.

Do not use forced tool use to fake structured text output. If you want JSON in the message body, prompt for it or use the structured-output path. Forcing a tool gives you a tool_use block, which your code has to unwrap. That is the right shape for actions, the wrong shape for "return me a JSON string." The same discipline shows up in our Claude tool use recipes.

Cost to test: $0.02 (four Claude Haiku 4.5 calls, one per mode, tiny prompts).