Tool Choice Options Reference

tool_choice is a top-level parameter on messages.create() that controls whether Claude uses a tool at all, and if so, which one. This page is a quick-reference for the four modes and the one modifier that applies to all of them.

How to Use This Reference

Look up the mode by what you need Claude to do this turn - decide freely, use something, use one specific thing, or use nothing.
Copy the matching Python snippet and swap in your own tool names.
Check the "Use it when" column before reaching for {"type": "tool", ...} by habit - auto is right for most conversational turns.
Add disable_parallel_tool_use only when your downstream code can't handle more than one tool call per turn.
Switching tool_choice between requests is caching-safe - see the caching note below before you avoid it for the wrong reason.

The Four Modes

Mode	Value	Claude's behavior	Use it when
Auto	`{"type": "auto"}`	Claude decides whether to use a tool, and which one, based on the conversation.	General-purpose conversational agents where tool use is optional most turns.
Any	`{"type": "any"}`	Claude must call one of the provided tools, but you don't pick which.	You know the turn should end in some action, but any of several tools would satisfy it.
Tool	`{"type": "tool", "name": "..."}`	Claude must call the exact tool you name.	Forcing structured extraction into one schema, or forcing a specific action regardless of what Claude would otherwise choose.
None	`{"type": "none"}`	Claude must not call any tool, even though `tools` is still in the request.	Temporarily suppressing tool use (e.g., a clarifying-question turn) without removing tool definitions from the request.

Note: auto is the default. Omitting tool_choice entirely when tools is present behaves the same as {"type": "auto"}.

Request Shapes

{"tool_choice": {"type": "auto"}}

{"tool_choice": {"type": "any"}}

{"tool_choice": {"type": "tool", "name": "get_weather"}}

{"tool_choice": {"type": "none"}}

Python Usage

Pass tool_choice as a kwarg to client.messages.create(...), same shape as the JSON above:

from anthropic import Anthropic
 
client = Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[weather_tool, calculate_tool],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "What is 12 times 5?"}],
)

Forcing one specific tool by name:

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

disable_parallel_tool_use

All four modes accept an optional "disable_parallel_tool_use": true flag alongside type. It caps Claude to at most one tool call per response, even in turns where it would otherwise call several tools in parallel. The default is false - parallel tool calls are allowed.

tool_choice={"type": "auto", "disable_parallel_tool_use": True}

Use it when your tool-execution code assumes exactly one tool_use block per turn and you don't want to add loop logic to handle several.

Choosing a Mode

auto - the default for agents and chat interfaces. Claude weighs the conversation against each tool's description and decides on its own.
any - use when the turn must result in some action but the choice of action is genuinely up to Claude - for example, a router turn where several tools could all be valid next steps.
tool - forces one named tool. This is an older pattern for structured data extraction; for pure data extraction, output_config.format structured outputs is often now a better fit. Forced tool_choice is still common when you need to force an action, not just a shape - like requiring a specific function call in a test harness or a guided workflow step.
none - suppresses tool use for one turn without dropping tools from the request. Removing tools entirely to stop tool use would invalidate the tools cache tier; setting tool_choice to none keeps the same tool definitions in the request so caching stays intact.

Caching Note

Changing tool_choice between requests does not invalidate the tools or system-prompt cache tiers. Only a model switch or an actual change to the tool definitions themselves breaks those cache tiers. That means toggling tool_choice per request - say, auto on most turns and none on a clarifying-question turn - is caching-safe, and you don't need to keep tool_choice constant to preserve your cache hit rate.

FAQs

What does Claude do if I omit tool_choice entirely?

Same as {"type": "auto"} - Claude decides on its own whether to call a tool, as long as tools is present in the request.

Does `{"type": "any"}` let me control which tool Claude picks?

No. It only guarantees Claude calls one of the tools you provided. If you need a specific tool, use {"type": "tool", "name": "..."} instead.

Can I use tool_choice: none to stop Claude from using tools for the rest of the conversation?

Only for the request it's set on. tool_choice is evaluated per call to messages.create(), so you'd set {"type": "none"} on every subsequent request where you want tool use suppressed.

Why keep `tools` in the request when I set tool_choice to none?

Removing tools entirely changes the request and invalidates the tools cache tier. Keeping tools in place and setting tool_choice to {"type": "none"} suppresses tool use for that turn while keeping the cached tool definitions intact.

Is forcing a tool with {"type": "tool", ...} still the right way to do structured data extraction?

It's still common and works fine, but for pure data-extraction use cases, output_config.format structured outputs is often now a better fit. Forced tool_choice remains the right call when you need to force an action, not just shape a response.

What happens if the named tool in {"type": "tool", "name": "..."} isn't in my tools list?

The request is invalid - the name must match one of the tools you passed in tools. Keep the tool list and the forced name in sync, especially if tool lists are built dynamically.

Does switching tool_choice between requests hurt my prompt cache hit rate?

No. Only model switches and actual changes to tool definitions invalidate the tools and system-prompt cache tiers. tool_choice itself is not part of what's cached, so toggling it per request is safe.

Does disable_parallel_tool_use change which tool Claude picks?

No, it only limits Claude to at most one tool call in that response. It works alongside any of the four type values - auto, any, tool, or none - it just changes how many calls come back, not the selection logic.

What's the default for disable_parallel_tool_use if I don't set it?

false. Claude may return multiple tool_use blocks in one turn unless you explicitly set disable_parallel_tool_use to true.

When would I reach for `any` instead of just leaving tool_choice on auto?

When you need a guarantee that the turn results in a tool call - auto lets Claude decide not to call anything, which is a problem if your flow assumes an action always happens.

Is `none` the same as not passing `tools` at all?

Functionally similar for that turn - no tool gets called either way - but they differ for caching. Omitting tools drops the cached tool definitions; {"type": "none"} keeps tools in the request so the cache tier survives.

Can I force a tool call and still let Claude add explanatory text?

Yes - forcing a tool controls whether/which tool is called, not whether Claude can also produce text content alongside the tool_use block, depending on the model's behavior for that turn.

Tool Use Basics - the full round trip including a tool_choice example in context
Executing Parallel Tool Calls in a Single Turn - handling multiple tool_use blocks when parallel calls aren't disabled
Defining Tool Schemas with name, description, and input_schema - what Claude reads to decide which tool fits, under auto
Best Practices - broader guidance for tool use and function calling on this stack

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.