Get Started
Agent engineering

Mission 3 of 8

Build tools an agent can actually use, and recover from when they fail.

Most agent failures are tool failures wearing a model's name. You'll rewrite two tools properly, add one with side effects, and build a registry you can reuse for the rest of the track.

70 minIntermediateUnder $0.50 of API creditStep 1 free

What you'll do

Write strict, well-described tools

Learn the five rules for descriptions, then build a registry that enforces strict schemas and fixed error shapes.

Make tools safe and recoverable

Sandbox the file tool, bound the calculator, and add a write tool that is idempotent and asks first.

Test tools without a model

Plug the registry into the loop, then pin each failure with pytest tests that never call the API.

  • A reusable tool registry with timeouts and a confirmation gate
  • Errors that tell the model what to do next
  • A structured result ready for the eval harness in mission 6
Before you start
  • Missions 1 and 2 done: agent-lab with agent.py, expenses.txt, venv active, key set
  • pip install pytest in the venv
  • 30 minutes of uninterrupted attention for steps 2 to 4. This is the densest mission in the track
Your progress0/6
01/06What a tool is to the model: name, description, schema0 done
STEP 01 of 06~8 min

What a tool is to the model: name, description, schema

The model never sees your function. It sees three strings. Get them right and half of your agent problems disappear.

Before you write any code, it helps to know exactly what the model is working from. When you send tools=[...], the API renders your definitions into the system prompt.

The model reads the name, the description and the JSON schema, and decides from those alone whether to call the tool and what to pass. Your function body is invisible. So tool design is prompt design with a type system attached.

A bad description and a good one

  1. Read the same function described twice below, and notice how much more the second one tells the model.

    Same function, two descriptions
    # Bad: true, useless. The model has to guess when, and gets no help with how.
    "description": "Reads a file."
    
    # Good: when to use it, what comes back, what it cannot do, and the defaults.
    "description": "Read lines from a UTF-8 text file inside the project folder. Returns total_lines,
    the requested lines, and more=true if the file continues past the window. Use start_line=1
    and max_lines=200 unless you need a different window. Cannot read outside the project folder."

Five rules

Each one was learnt from an agent doing something stupid:

  • Say when to use it and when not to. Use this for every sum, average or comparison; never do arithmetic in your head. That sentence moves the "did it use the calculator" rate more than anything else you can do.
  • Say what comes back. If the result has total_lines and more, name them. The model plans its next call around the shape it expects.
  • Say what it cannot do. Cannot read outside the project folder stops the model wasting a turn trying, and stops it apologising to the user for a limit that is deliberate.
  • Name things the way a human would. read_file, not fs_read_v2. expression, not expr_str. The model has read millions of codebases; match their conventions and it guesses right.
  • One tool, one job. A do_file_things tool with an action enum is three tools pretending to be one, and the model picks the wrong action more often than it picks the wrong tool.

Defaults belong in the description

Descriptions are also where you put defaults when the schema cannot: Use start_line=1 and max_lines=200 unless you need a different window.

Strict schemas, next step, require every field, so the description tells the model what to fill in.

Tip
Steal from the best. The tool descriptions in Claude Code and in Anthropic's own bash and text editor tools are long, specific and full of "do not" clauses. Long is fine. Tokens spent in a description are spent once per request; tokens spent on a wrong tool call are spent on every retry.
Checkpoint
You have rewritten the two mission 1 descriptions on paper (or in agent.py) to follow all five rules, before writing any new code.
Stuck? Ask the community
Next mission · Agent engineeringMemory that doesn't lie: context budgets, a SQLite long-term store, and the two ways memory goes wrong
→