What are the tool_choice modes in Anthropic's Messages API?

## Where it sits `tool_choice` is a top-level parameter on `POST /v1/messages`, a sibling of `tools`. It is an object, not a string — `tool_choice: "auto"` is not valid on Anthropic's API even though other vendors accept the bare string form. If you omit it while `tools` is present, the server behaves as `{"type": "auto"}`. ## The four modes **`auto`** — Claude decides. It may answer in plain text, or emit one or more `tool_use` blocks, or mix a text block and tool calls in the same assistant message. This is what you want for almost all agent work, because the model's judgement about whether a tool is needed is usually the point of giving it tools. **`any`** — Claude must emit at least one `tool_use` block. It cannot answer with text alone. Use this when the turn *has* to produce an action and there are several plausible actions to choose between. **`tool`** — takes a required `name` alongside the type, and forces that one tool. The dominant real-world use is not agency at all but structured extraction: declare a single tool whose `input_schema` is the record you want, force it, and read the arguments off the resulting `tool_use` block. That gives you schema-shaped output without parsing prose. **`none`** — Claude may not call anything. The tool definitions stay in the request (and stay billed as input tokens), so the prefix and its cache remain intact; only the model's permission changes. This is how you close out an agent loop: same conversation, same tools, but this turn must produce the final prose answer. ## disable_parallel_tool_use By default Claude may return several `tool_use` blocks in one assistant message so you can execute them concurrently. Adding `"disable_parallel_tool_use": true` to whichever `tool_choice` object you are sending caps it at one call per response. It is a key *inside* the `tool_choice` object, not a separate top-level parameter. Reach for it when your tools mutate shared state and concurrent execution would race, or when you want one-step-at-a-time behaviour you can approve individually — at the cost of more round trips and higher end-to-end latency. ## The trap: forcing is a per-request setting, not a session setting Forced modes describe *this* request. In an agent loop you build a fresh request each turn from the accumulated `messages`, so whatever `tool_choice` you pass is re-applied every time. Passing `any` or `tool` from a constant means every turn is required to call a tool, and the model can never reach a natural end of turn. The standard pattern is to force on the first turn only, then switch to `auto` for the rest of the loop. ## Vendor confusion OpenAI's equivalent parameter uses `"required"` where Anthropic uses `"any"`, and accepts bare strings. Gemini expresses the same idea as a `tool_config` with `AUTO` / `ANY` / `NONE` function-calling modes. Porting code across these without adjusting the literal values produces a 400 rather than a subtle behaviour change, which is at least a fast failure — but recalling the wrong literal in an interview is a visible tell. ## Interaction with tool descriptions Forcing is a blunt instrument and is often reached for to paper over a weak description. If the model is not calling a tool you believe it should, the first fix is a description that states the trigger condition, not `tool_choice: any`. Forcing changes the model's options; it does not improve its judgement about which tool fits, and with several tools declared a forced `any` can push it into calling the wrong one rather than the none it correctly wanted. ## Choosing in practice Use `auto` by default. Use `tool` for one-shot structured extraction and for the deterministic first step of a pipeline. Use `any` sparingly, when a no-op turn is genuinely invalid. Use `none` for a final summarisation turn, or to temporarily disarm a dangerous tool surface without rebuilding the request and losing the cached prefix. Add `disable_parallel_tool_use` only when concurrency is actually unsafe.