AI Systems Atlas

T-01Designing Tools for Agents

/tools/tool-design

A tool is an interface for a model, not a wrapper around an endpoint: its name, description, schema and return shape are everything the model knows about it.

Step-by-step walkthrough2 variants · 12 steps

API wrappers

  1. The task is one sentence: book thirty minutes with Ana next week.
  2. But the tools mirror the API, one endpoint each. The agent has to orchestrate them itself.
  3. Call 1 lists every user so it can find Ana — four thousand rows of ids, all of it now in context.
  4. Call 2 dumps the calendar, so the model can find a free slot by reading it.
  5. Call 3 books with an id copied out of row 2,317. One wrong character and it is someone else’s meeting.
  6. Three round trips, and most of the window went on plumbing the tool should have done.

Agent-shaped

  1. The same one-sentence task.
  2. This time there is one tool shaped like the task, not like the API.
  3. Its description says when to use it and what comes back; the schema takes a name and a length, not a uuid.
  4. The lookup, the free slot and the booking happen inside the tool — deterministic code, not tokens.
  5. It returns only what the next step needs: a name, a time, a status.
  6. One call, one short result — and the agent never handled an identifier it could mistype.
Key insight

Shape tools around the tasks an agent actually performs. One schedule_event that does the lookup, the availability check and the booking in code beats three endpoints the model has to stitch together in tokens.

Failure mode

Wrapping every endpoint one-to-one and returning raw JSON. The agent spends its window on plumbing, copies opaque ids between calls, and picks the wrong one of three near-identical tools.

Further reading
RelatedTool errors as observationsObservation compressionTool poisoning

Elsewhere in the atlas

Harnesses →Security →Evals →Context →Coding Agents →Ops →