Catalog / Single agent

Tool use

The model never touches a system directly. It reads tool descriptions, emits a structured call, and the application runs it and returns the result.

Reference task used across all patterns: "My order arrived damaged. Can I get a refund?"

Topology

ActorLead agentTool

Run

08 steps

Ready to run

Play runs the whole scenario. Step advances one event at a time so you can read what happens.

Metrics

Wall-clock time0.0 s
Tokens processed0
Estimated cost$0.000
Tool calls
0
Illustrative values. They show proportions between patterns, not benchmarks.

All steps

Normal run

  1. Request arrives. Alongside the message, the model receives a list of tools. Each has a name, a description and typed parameters.
  2. Choose a tool. Those descriptions are all the model knows about the systems behind them. It picks the order lookup because the description says what it returns.
  3. Structured call. The model does not run anything. It emits a call as data, and the application executes it and checks the arguments against the schema.
  4. Result. The result comes back as text in the model's context. It names the unit, so there is nothing to guess.
  5. Decide. Delivered 12 Sep, inside the 30-day window, damage confirmed by the carrier. A full refund is due.
  6. Call with exact arguments. The parameter is named amount_cents, so the model converts $240 to 24000. A clear name did that work, not intelligence.
  7. Confirmation. The tool echoes what it did in human terms, which lets the model notice a mismatch.
  8. Respond. Refund approved. Two calls, both well-formed on the first try.

Outcome: correct answer. The tools were written for a reader that knows nothing but their descriptions. Names carried units, results were readable, and the schema caught what it could.

Failure mode

  1. Request arrives. Same agent and same systems. Only the tool definitions differ.
  2. Look up the order. The lookup works as before.
  3. Result. Order 4417, total 240. This build's result drops the currency and the unit.
  4. An ambiguous contract. The refund tool's schema says only “amount: number”. Dollars or cents? The description does not say, so the model has to guess.
  5. A valid, wrong call. It guesses dollars. The payments API takes cents. The call passes schema validation, because 240 is a perfectly good number.
  6. Success, technically. The tool returns a bare “ok”. Nothing in the result lets the model see what actually happened.
  7. Incorrect response. The agent reports success. The customer receives $2.40 for a $240 order.

Failure: an ambiguous tool contract. The model did what the description allowed. Mitigation: put units in parameter names, document each tool as if for a new colleague, validate ranges inside the tool, and return results the model can sanity-check.

Execution trace

Model workingSending a message

Reference

Problem
A model can only produce text, but the task needs facts from live systems and actions with real effects.
Analogy
A new employee with a phone list. They can only do what the list lets them ask for, and only as well as each entry is described.
Use when
The answer depends on data the model does not have, or the task ends in an action. This is the base of almost every other agent pattern.
Avoid when
The model can answer from its context alone. Every tool adds latency, tokens for its description, and a new way to be wrong.
Typical failure
An ambiguous tool description or schema leads to a call that is well-formed and wrong.
Also known as
Tool use (Anthropic)Function calling (OpenAI)Function tools (OpenAI Agents SDK)
Related patterns
Sources

Space play or pause   → next step   ← previous step  R reset   F failure mode