tool_choice has three modes. Choosing the wrong one is a common source of pipeline failures.
| Mode | Guarantee | Use when |
|---|---|---|
Forced ({type: tool, name: X}) | Specific tool called every time | Single-schema pipeline |
Any ({type: any}) | Some tool called, Claude picks which | Multi-schema, guaranteed output |
Auto ({type: auto}) | Tool use optional — may return text | Some inputs don’t need structure |
The Data: 500 Mixed Documents, 3 Extraction Tools
| Mode | Tool call rate | Wrong schema |
|---|---|---|
| Forced (one tool) | 100% | 34% |
| Any | 100% | 3% |
| Auto | 87% | 2% |
Any is optimal for multi-tool pipelines. It achieves both 100% tool calls and high schema accuracy — Claude picks the right tool while guaranteeing structured output.
Auto Mode: The Guaranteed-Output Anti-Pattern
Auto mode lets Claude return text instead of calling a tool. In 13% of requests, this happened — bypassing the schema entirely and breaking downstream parsing.
No amount of tool description improvement can guarantee auto always calls a tool. The any mode provides this guarantee by design. Use auto only when some inputs genuinely should not produce structured output.
Forced Mode: The Multi-Schema Anti-Pattern
Forcing one tool on all document types applies the wrong schema to non-matching documents. Even when 90% of documents are invoices, forcing extract_invoice on receipts produces 34% wrong-schema output.
For multi-schema pipelines, any mode lets Claude select the appropriate tool while guaranteeing a tool is always called.
When Auto IS Correct
A pipeline receives both code files (need structured analysis) and README files (need text summary). Auto lets Claude use the analysis tool for code and return text for READMEs. This conditional behavior is auto’s valid use case.
Sequential Extraction Pattern
For two-phase extraction (metadata first, then enrichment):
- Phase 1: Forced tool_choice — guarantees metadata extraction
- Phase 2: Auto — allows conditional enrichment (skip when unnecessary)
Forcing both phases produced 15% empty enrichment fields. Auto for Phase 2 lets Claude skip enrichment when the document does not warrant it.
One-liner: Use forced for single-schema pipelines, any for multi-schema guaranteed output, and auto only when some inputs genuinely should not produce structured output — the wrong mode causes 13-34% pipeline failures.