CCA-F
Sign inStart Free

tool_choice

Tools

Definition

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 CCA-F Exam

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 whose input_schema describes your desired output shape, set tool_choice to that tool, and Claude will populate input with conforming data. The response content will be a tool_use block 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

ValueTool use guaranteed?Which tool?Typical use case
autoNoClaude's choiceGeneral-purpose agent turns
anyYes (≥1 tool)Claude's choice from listPipeline stages requiring structured capture
toolYes (exactly one)Named tool onlyForced structured output, schema extraction
noneNeverN/AExplanation turns, read-only reasoning phases

Example

Using tool_choice: {type: "tool"} to guarantee structured extraction — Claude cannot respond in plain text.

javascript
// 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 Engineering

Tool use with JSON schemas eliminates syntax errors but not semantic errors

tool_choice Options & Forced Tool Selection

Prompt Engineering

tool_choice: 'auto' may return text; 'any' guarantees a tool call; forced selection guarantees a specific tool

Related Terms

tool_useStructured Output
← Back to Glossary