tool_choice
ToolsDefinition
API parameter controlling how Claude selects tools. 'auto' (default): Claude decides whether to use tools. 'any': Claude must use at least one tool. 'none': Claude cannot use tools. '{type: tool, name: X}': Claude must use the specific named tool. Used to force structured output via a schema tool.
Example Usage
Set tool_choice: {type: 'tool', name: 'extract_data'} to force Claude to use your extraction schema and guarantee structured JSON output.
Why It Matters for the Claude Certification Exams
Exam questions typically give a scenario — "you need to guarantee Claude returns structured JSON" or "you want Claude to never call tools on this turn" — and ask which `tool_choice` value achieves it. Know that `auto` does not guarantee tool use, `any` guarantees at least one, `tool` guarantees a specific one, and `none` disables all tool use.
In Depth
The tool_choice parameter gives you direct control over whether and how Claude selects tools on a given API call. It accepts one of four shapes:
{type: "auto"}(default): Claude decides. If tools are listed and calling one would help, Claude calls it. If plain text suffices, Claude responds in prose. This is appropriate for general-purpose agents where tool use is situational.{type: "any"}: Claude must use at least one tool from the provided list. Use this when you need to guarantee that structured data is captured — for example, when routing a user request through a classification tool before the next pipeline stage.{type: "tool", name: "<tool_name>"}: Claude must call the specified tool. This is the primary mechanism for forcing structured JSON output: define a tool whoseinput_schemadescribes your desired output shape, settool_choiceto that tool, and Claude will populateinputwith conforming data. The responsecontentwill be atool_useblock rather than text.{type: "none"}: Claude cannot use any tool even if tools are listed in the request. Useful for read-only or explanation turns within a loop where tool access should be suspended.
A key distinction on any vs. tool: any means Claude picks freely among available tools; tool pins Claude to one specific tool. Both guarantee tool invocation; the difference is specificity.
For structured output extraction, tool_choice: {type: "tool", name: "extract"} combined with a well-defined schema is often cleaner than prompt-level instructions, because Claude is constrained at the API contract level rather than the text level. See also Structured Output via Tool Use and the tool_choice Options concept guide.
Note that parallel tool use still applies under any — Claude may return multiple tool_use blocks even though you only required at least one.
When tool_choice is tool and the named tool is not in the tools list, the API returns a validation error. Always verify the name matches exactly.
How It Compares
| Value | Tool use guaranteed? | Which tool? | Typical use case |
|---|---|---|---|
auto | No | Claude's choice | General-purpose agent turns |
any | Yes (≥1 tool) | Claude's choice from list | Pipeline stages requiring structured capture |
tool | Yes (exactly one) | Named tool only | Forced structured output, schema extraction |
none | Never | N/A | Explanation turns, read-only reasoning phases |
Example
Using tool_choice: {type: "tool"} to guarantee structured extraction — Claude cannot respond in plain text.
// Force structured extraction with tool_choice: tool
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
tools: [
{
name: "extract_issue",
description: "Extract structured fields from a bug report.",
input_schema: {
type: "object",
properties: {
title: { type: "string" },
severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
component: { type: "string" },
},
required: ["title", "severity", "component"],
},
},
],
tool_choice: { type: "tool", name: "extract_issue" },
messages: [
{ role: "user", content: bugReportText },
],
});
// Response will always be a tool_use block — no prose fallback
const toolUse = response.content.find(b => b.type === "tool_use");
const fields = toolUse.input; // { title, severity, component }Frequently Asked Questions
Does `tool_choice: any` mean Claude will always call every tool in the list?
No. `any` means Claude must call at least one tool from the list — it might call just one, or it might call several in parallel. It does not mean all tools are invoked.
Can I use `tool_choice: tool` as a replacement for structured output via `output_config`?
They solve similar problems but operate differently. `tool_choice: tool` constrains Claude to call a specific tool and populate its `input_schema`, giving you a JSON object. `output_config: {format: {type: "json_schema"}}` constrains the top-level text response. The tool approach is often preferred in agentic loops where the output is consumed programmatically, while `output_config` is better when you want the text itself to be valid JSON.
Referenced in These Lessons
Structured Output via Tool Use & JSON Schemas
Prompt EngineeringTool use with JSON schemas eliminates syntax errors but not semantic errors
tool_choice Options & Forced Tool Selection
Prompt Engineeringtool_choice: 'auto' may return text; 'any' guarantees a tool call; forced selection guarantees a specific tool