Anthropic Tool Use & Adaptive Thinking
How to build production tool-using agents with the Anthropic SDK: tool definitions with strict mode and input examples, the five tool_choice modes and their interaction with adaptive thinking, server tools, model tier selection with cost math, and the checklist that prevents the most common agent failures.
Quick Reference
- →Tool definitions use `input_schema` (JSON Schema) — add `strict: true` for schema conformance, `input_examples` to improve tool selection accuracy
- →Five `tool_choice` modes: `auto` (default), `any` (force a tool), `tool` (specific tool), `none` (suppress all tools), omit tools (no tools available)
- →Adaptive thinking + `tool_choice: 'any'` or a named tool = 400 error — thinking only supports `auto` or `none`
- →Adaptive thinking (`thinking: {type: 'adaptive'}`) replaces deprecated `budget_tokens` — control depth with `effort: 'low'|'medium'|'high'`
- →Thinking blocks in multi-turn tool loops must be preserved in the messages array — stripping them returns a 400 on the next call
- →Server tools (web_search, code_execution, web_fetch) run on Anthropic infrastructure with no execution loop — always set `max_uses` to cap spend
Tool Definitions: What Claude Sees
Claude decides when to call a tool based on three signals: name, description, and input_schema. It never sees your implementation. The description is the primary routing signal — write it to answer 'when should I use this?' not 'what does this do?'. A description that says 'search the documentation' is weaker than one that says 'search the product documentation when the user asks about features, API endpoints, or pricing. Do NOT use for general web searches.' The second tells Claude exactly when to reach for the tool and when to skip it. Two newer features improve tool selection reliability: strict: true constrains decoding so every tool call exactly matches your input_schema — no extra fields, no missing required fields. Add input_examples for tools with complex or nested inputs; they act as worked examples embedded in the prompt, showing Claude how to construct valid inputs.
Each design layer adds precision — name catches misses, description adds context, schema constrains args, examples nail edge cases
With strict: true, every property in the schema must appear in the required list — there are no optional fields. If a field is genuinely optional, either add it to required with a nullable type (e.g., {type: ['string', 'null']}) or omit strict: true and validate inputs yourself before execution.