Choose whether a turn requires tools

Learning objective

Compare tool_choice (auto, any, named tool, and none) and its implications for whether Claude may respond without a tool call.

Core idea

The Messages API separates the available tools from the rule for choosing them. The top-level tools array defines the menu. The top-level tool_choice object controls whether Claude can decline that menu, must select from it, must request a named operation, or must avoid tools for the response.

Use the mode that matches the turn’s purpose. A question that can be answered from supplied evidence can use auto. A turn that requires some tool can use any where forcing is supported. A turn that requires one particular operation can use named tool where supported. A final response that should use no tools can use none.

These are response-selection controls. A requested client-tool call is not proof that the operation ran, succeeded, or met a business prerequisite. Your application executes client tools and interprets their results. See 1.1.3 for model selection versus fixed sequences, and 2.3.5 for mandatory first-step ordering.

How it works

Compare the four request shapes

The following modes control the model’s choice for the response:

extract_metadata is an application-defined example. The named mode refers to the operation’s tool name, not a natural-language instruction or the name of an agent. You still supply the corresponding definition in tools.

When tools are provided, auto is the documented default. When no tools are provided, none is the documented default. Do not infer that adding a tools array makes a call mandatory. A tool-enabled request can still produce an answer or clarification without selecting a tool under auto.

Distinguish preference from forcing

A user message that says “use the metadata tool” can influence auto selection. Anthropic documents this pattern when you want natural-language context before the call. It does not change auto into a mandatory tool-use rule. If the architectural requirement is that a call occurs, select a supported forcing mode or enforce the requirement through application control flow.

With any, the model retains the choice of tool. If the menu includes both extract_metadata and enrich_record, any requires a tool request but does not establish which one starts the workflow. Named tool removes that choice for the response. The decision between them turns on whether any eligible operation suffices or one operation is specifically required.

Forcing through any or tool also changes the response prefix. Anthropic documents that the API prefills the assistant message, so the model does not emit a natural-language explanation before the tool_use blocks. Forcing skips thinking on models that accept it: the response starts with the tool call and contains no thinking block. Use auto when thinking before selection is part of the desired behavior.

Separate call requirement from call count

Claude may return multiple tool requests in a response by default. any therefore should not be read as “exactly one call.” It expresses a required selection from the menu. If the workflow needs one call, put disable_parallel_tool_use: true inside tool_choice.

With type: "auto", that nested field means at most one call; a tool-free response remains possible. With supported any or tool, it means exactly one call. The field is not a top-level request parameter. See 2.3.5 for using this distinction when an initial extraction must precede enrichment.

The application still chooses how to execute client-tool requests. The API’s parallel-tool documentation does not prescribe an execution order for ordinary client tools. A single assistant response containing two requests is not evidence that one result informed the other. Count, selection, and execution dependency are separate decisions.

Keep support separate from intent

Not every model and thinking setting supports any or named tool. Unsupported forcing configurations fail; auto and none remain the documented alternatives. Manual extended thinking with thinking: {"type": "enabled"} does not support forcing. Some models reject forcing regardless of thinking settings. See 2.3.5 for the named model restrictions and the fallback architecture.

Do not handle a forcing error by silently accepting a tool-free answer as if the original requirement were satisfied. Change to a supported control path and preserve the operation’s prerequisite. A different response-selection mode changes what the model may emit; it does not remove the application’s workflow obligation.

Key distinctions and trade-offs

auto versus any: auto supports direct answers and clarification. any requires a tool on supported configurations but leaves tool identity to Claude. Choose based on whether the turn genuinely requires execution.

any versus named tool: any permits selection among the menu’s entries. Named tool requests the specified operation. Neither is a complete multi-step workflow definition.

none versus deleting the registry: none prevents tool use in this response even when definitions remain in the request. It is useful for a synthesis turn whose required evidence has already been collected. The application can select a different mode on a later request.

Forced selection versus successful execution: A tool_use block carries the requested operation. Your dispatcher and the corresponding tool_result establish what happened. See 1.1.2 for matching results to calls.

Architecture / decision scenario

A structured-data extraction service uses extract_metadata and enrich_record, both application-defined tools. Its architect assigns a mode for each kind of turn instead of applying one mode to every request.

When a user asks whether supplied text contains enough information to begin, the service uses auto. Claude can answer or ask for missing input without an unnecessary operation. When a supported configuration must perform one of several eligible lookup operations, the service uses any; it does not claim that this selects extraction specifically.

For an initial turn that specifically requires metadata extraction, the service uses named tool with name: "extract_metadata", subject to the support checks in 2.3.5. If exactly one call is intended, it nests disable_parallel_tool_use: true in the same object. After execution and validated results, follow-up turns can use auto for eligible enrichment choices.

For the final explanation, the service uses none to summarize collected evidence without initiating another operation. If the model or thinking configuration rejects forcing, the service switches to the gated application flow from 2.3.5. The four modes serve four different response decisions; none substitutes for checking execution outcomes.

Common exam traps

• Assuming tools alone guarantees a call.
• Reading any as a requirement to call one particular tool.
• Setting any to stop Claude choosing the wrong tool: it forces some call but leaves the choice among tools to Claude, so repair descriptions or the menu instead (see 2.1.2 and 2.3.1).
• Reading any as exactly one call without disabling parallel tool use.
• Reading the guide’s tool_choice: "any" shorthand as a different mode from {"type": "any"}.
• Expecting a pre-call explanation or thinking block from a forced response.
• Treating unsupported forcing as a prompt-quality problem.

Where the exam guide differs

What to remember

auto permits a tool-free response, any requires a provided tool where supported, named tool requires the specified operation where supported, and none prevents tool use. disable_parallel_tool_use controls call count separately. Match the response rule to the turn and retain application responsibility for execution and ordering.

Knowledge check

References

• Anthropic, Define tools
• Anthropic, Parallel tool use
• Anthropic, Handle tool calls
• Anthropic, Claude Certified Architect – Foundations Exam Guide