tool_choice Options & Forced Tool Selection
CoreEnforce structured output using tool use and JSON schemas · Difficulty 3/5
Explanation
The `tool_choice` parameter controls whether and which tools the model calls. Understanding the options is critical for reliable structured output.
tool_choice Options
| Value | Behavior | Use When |
|---|---|---|
"auto" | Model may return text instead of calling a tool | Default; model decides if a tool is helpful |
"any" | Model must call a tool but can choose which | Multiple extraction schemas, unknown document type |
{"type": "tool", "name": "extract_metadata"} | Model must call the specific named tool | Ensuring a particular extraction runs before enrichment |
When to Use Each
auto: When you want the model to decide whether structured output is appropriate. Risk: model may return plain text when you need structured data.
any: When you have multiple extraction tools and don't know which one fits. Guarantees structured output but lets the model pick the right schema.
Forced tool: When a specific extraction must happen as a pipeline step. Use {"type": "tool", "name": "tool_name"} to ensure the model calls exactly that tool.
Extraction Pattern
Define extraction tools with JSON schemas as input parameters. The structured data comes from the tool_use content block in the response, not from text output.
Key Takeaways
- tool_choice: 'auto' may return text; 'any' guarantees a tool call; forced selection guarantees a specific tool
- Use 'any' when multiple extraction schemas exist and document type is unknown
- Use forced tool selection to ensure a specific extraction runs before enrichment steps
- Extract structured data from the tool_use content block, not from text output
Glossary Terms
Related Concepts