85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Glossary

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.

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.