What are tool use examples?
Tool use examples are sample tool calls attached to a tool's definition that show a model which optional parameters to fill, which formats to use and how to structure complex inputs, conventions a JSON Schema cannot express.
A JSON Schema says what shape a tool's input must have. It does not say when an optional field should be filled, which combinations make sense, or which date or ID format an API expects. Models fill those gaps by guessing, and the guesses cause malformed calls.
Anthropic introduced tool use examples in "Introducing advanced tool use" (2025-11-24), alongside tool search and programmatic tool calling. Developers add an input_examples array to a tool definition, and the examples are placed in the prompt next to the schema. In Anthropic's internal testing, examples raised accuracy on complex parameter handling from 72% to 90%.
How to write them
One to five per tool
Anthropic suggests a small set, chosen for variety rather than volume.
Realistic data
Real-looking values, not placeholders like "string" or "value".
Minimal, partial and full
Show a call with only required fields, one with some optional fields and one fully specified.
Aim at the ambiguity
Add examples where correct usage is not obvious from the schema, and nowhere else.
Rules and costs
Must validate
Each example has to be valid against the tool's input schema; an invalid one returns a 400 error.
Not for every tool type
Examples work on user-defined tools and most Anthropic client tools, but not on server tools such as web search or code execution, or on the computer use and browser use toolsets.
Token cost
Anthropic's documentation estimates about 20 to 50 tokens for a simple example and about 100 to 200 for a complex nested one.
When to use them and when not
They earn their tokens on complex nested inputs, tools with many optional parameters, domain-specific API conventions, and sets of similar tools where an example clarifies which one to pick.
They are wasted on simple tools with one obvious parameter, on standard formats such as URLs and emails, and on rules the schema can enforce directly. Anthropic's documentation still ranks a clear, detailed description as the most important factor in tool performance; examples come second.
What they are confused with
Few-shot prompting
Few-shot examples sit in the prompt and show whole input and output pairs. Tool use examples sit on the tool and show only the call.
Strict mode
Strict tool use guarantees the call matches the schema. Examples teach which valid call to make.
How Motiontic's engineers apply it
Motiontic's engineers add examples when traces show a recurring malformed call, such as a wrong date format or a missing optional field that the downstream API needs, and keep them only if the eval set shows the error rate drop.
Common questions
What is input_examples in the Claude API?
It is an optional array on a tool definition holding sample inputs that must validate against the tool's schema. Claude sees them alongside the schema and uses them as patterns for its own calls.
How many tool use examples should a tool have?
Anthropic suggests one to five, covering minimal, partial and fully specified calls, and only where the schema leaves real ambiguity.
Do tool use examples replace tool descriptions?
No. Anthropic's documentation calls detailed descriptions the most important factor in tool performance. Examples supplement them for complex inputs.
Related
Tool calling
How a model asks software to do something: a named tool, typed arguments, a result.
Agent-computer interface (ACI)
The tools, docs and outputs an agent sees, designed as carefully as a UI.
Few-shot prompting
Teaching a model the task by showing a few examples, not by retraining it.
Tool search
Load tools when they are needed, not all at once before the work starts.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.