
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.
What you'll do
Learn the five rules for descriptions, then build a registry that enforces strict schemas and fixed error shapes.
Sandbox the file tool, bound the calculator, and add a write tool that is idempotent and asks first.
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
- Missions 1 and 2 done:
agent-labwithagent.py,expenses.txt, venv active, key set pip install pytestin the venv- 30 minutes of uninterrupted attention for steps 2 to 4. This is the densest mission in the track
Your progress0/6
- 01What a tool is to the model: name, description, schema8 min
- 02Strict schemas and a registry that enforces them14 min
- 03Rewrite the tools: bounded, sandboxed, with hints16 min
- 04Wire descriptions, timeouts and the confirm gate10 min
- 05Plug the registry into the loop and re-run the five experiments12 min
- 06Test the tools without a model, then expose them over MCP10 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
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_linesandmore, name them. The model plans its next call around the shape it expects. - Say what it cannot do.
Cannot read outside the project folderstops 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, notfs_read_v2.expression, notexpr_str. The model has read millions of codebases; match their conventions and it guesses right. - One tool, one job. A
do_file_thingstool with anactionenum 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.
agent.py) to follow all five rules, before writing any new code.