D2 · Tool Design & MCP › Cluster 1 · Tool Use Fundamentals

1.4 · tool_choice (auto / any / tool / none)

Force, allow, or forbid tools

CONCEPT One parameter, four modes

The tool_choice parameter controls whether Claude may, must, or must not call a tool on this turn. It has four values:

ValueEffectDefault when…
{"type": "auto"}Claude decides whether to use any tool or answer directly…tools are provided
{"type": "any"}Claude must use one of the provided tools (any of them)—
{"type": "tool", "name": "x"}Claude must use the specific named tool—
{"type": "none"}Claude cannot use any tool…no tools are provided
🔑 any and tool force a tool call — auto merely allows one. Use forcing when the task must route through a tool (e.g. structured extraction); use auto for conversational agents that should answer directly when they can.

CONCEPT Forcing prefills the assistant — no preamble

When tool_choice is any or tool, the API prefills the assistant message to force a tool call. The consequence: Claude emits the tool_use block directly, with no natural-language text before it — even if you asked it to explain first.

Want both an explanation and a specific tool? Keep tool_choice: auto and instruct in the user message: "…Use the get_weather tool in your response." That preserves the natural-language preamble while still steering the choice.
⚠️ With extended thinking enabled, any and tool are not supported and return an error — only auto and none are compatible. Some models (e.g. Mythos Preview) also reject forced tool use with a 400.

DIAGRAM How each mode routes the turn

flowchart TD R["Request with tool_choice"] --> M{"Which mode?"} M -->|"auto"| A["Claude decides:
tool OR direct answer"] M -->|"any"| B["Must call SOME tool
(prefilled → no preamble)"] M -->|"tool: name"| C["Must call THAT tool
(prefilled → no preamble)"] M -->|"none"| D["No tools — answer directly"] classDef allow fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef force fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef off fill:#f1f3f5,stroke:#adb5bd,color:#495057; class A allow; class B force; class C force; class D off;

CODE Forcing a specific tool

Force get_weather, and separately cap the turn to one tool call with disable_parallel_tool_use (valid on any tool_choice).

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    tools=tools,
    # Force THIS tool. Claude emits tool_use with no text preamble.
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "Weather in Paris?"}],
)

# "any" forces SOME tool; add disable_parallel_tool_use to
# cap the turn to at most one tool call.
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools,
    tool_choice={"type": "any", "disable_parallel_tool_use": True},
    messages=[{"role": "user", "content": "Book a flight to Tokyo."}],
)

# "none" forbids tools entirely — Claude answers directly.
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools,
    tool_choice={"type": "none"},
    messages=[{"role": "user", "content": "Just chat with me."}],
)

TRADE-OFFS Force a tool vs. let Claude choose

✅ any / tool (force)

  • Guarantees the turn routes through a tool — good for pipelines & extraction
  • Pair with strict: true to also guarantee schema-valid input
  • Deterministic control flow

⚠️ Cost of forcing

  • No natural-language preamble (prefilled assistant turn)
  • Incompatible with extended thinking
  • Can push a tool call where a direct answer was better → use auto for chat

EXAM TRAPS

Trap: "any forces a specific tool." → No — any forces some tool (Claude picks which). Use {"type": "tool", "name": …} to force a particular one.
Trap: Expecting a text preamble under any/tool. → Forcing prefills the assistant, so Claude jumps straight to tool_use with no explanation. Use auto + a user-message instruction if you want both.
Trap: Forcing tools with extended thinking on. → any and tool are not supported with extended thinking and error out; only auto and none work.
Trap: Getting the defaults backwards. → auto is the default when tools are provided; none is the default when no tools are provided.

PRACTICE

Q1 · Which tool_choice values force a tool call, and what's the difference?

any and tool. any forces Claude to use one of the provided tools (its pick); {"type": "tool", "name": "x"} forces that specific tool. auto only allows a call; none forbids all tools.

Q2 · Why does forcing a tool suppress Claude's usual explanation text?

Because any/tool prefill the assistant message to force a tool call, so the response begins with the tool_use block — no natural-language preamble. To keep an explanation, use tool_choice: auto and ask for the tool in the user message.

Q3 · You have tools defined but pass no tool_choice. What happens?

The default is {"type": "auto"} whenever tools are provided — Claude decides per turn whether to call a tool or answer directly. (With no tools provided, the default is none.)