Designing Tools an Agent Can Use
A tool is a UI for the model. Crisp name, tight schema, right size, and errors it can act on — that’s most of agent reliability.
Last lesson showed that a tool’s description is its selection logic. This lesson zooms into the tool itself: a well-built tool turns a flaky agent into a reliable one, and a badly-built tool makes even the best model look stupid. The mindset shift: a tool is a user interface — for the model. Just as a confusing app frustrates a person, a confusing tool frustrates the model. So what makes a tool the model can wield confidently? Hold the question: if the model is your “user,” what does a good tool look like?
Name + description: unmistakable and non-overlapping
From last lesson: the name and description are the selection logic, so make them specific and distinct. A good description says exactly what the tool does, when to use it, and when not to. “get_weather: returns the current weather for a city; use for weather questions, not forecasts” beats “weather: weather stuff.” If you have two tools that could be confused, spell out the boundary in each description. The words are doing real work — treat them like code, not marketing.
Tight, typed schemas and the right granularity
The argument schema is a contract (Module 2’s structured output, now pointed the other way). Make every field typed and constrained: enums instead of free strings (unit: "celsius" | "fahrenheit"), exact formats (date: YYYY-MM-DD), required vs optional marked. The tighter the schema, the fewer ways the model can fill it wrong. Equally important is granularity: one giant do_everything tool with 20 modes is hard to call correctly, but 50 hyper-specific tools overwhelm selection (last lesson). Aim for tools that each do one clear job — the same “one new step” instinct that makes good lessons makes good tools.
Loosening vs tightening a schema: • Loose:book(details: string)— the model crams everything into one blob; a hundred ways to get it wrong. • Tight:book_table(restaurant_id: string, date: YYYY-MM-DD, time: HH:MM, party_size: integer)— every field typed and named, so the model fills it correctly and your code can validate before running.
Errors the model can act on
Tools fail — a booking is full, an id is bad, a service times out. The rookie mistake is returning a raw stack trace or a bare “Error 500,” which the model can’t learn from. Instead return an actionable error: a short message that tells the model what went wrong and what to try next. “No tables at 7pm; available: 6:30, 8:00” lets the agent re-plan (Module 9’s whole theme); “Error” just makes it flail or give up. Because the loop feeds tool results back to the model, your error text is input to its next decision — so write it for the model to read, like a helpful teammate, not a log file.
Designing a tool is designing a form for someone to fill out — except the “someone” is the model. A bad form has one giant blank box labeled “details,” no hints, and when you make a mistake it just flashes “ERROR” with no clue what to fix. A great form has clearly labeled fields, dropdowns instead of free text, obvious required boxes, and error messages like “date must be in the future.” People fill great forms correctly and fumble bad ones — and so does the model. Build the tool the way you’d build a form you actually want filled out right.
Rebuilding a bad tool into a good one: 1. Before:manage_order(action: string, data: string)— vague name, two free-text fields, returns “failed” on any error. The agent guesses actions and mis-formats data constantly. 2. Split by job:cancel_order(order_id),refund_order(order_id, reason), each with a typed id. 3. Add actionable errors:refund_orderon a too-old order returns “Order older than 30 days; refunds not allowed — offer store credit instead.” 4. Now selection is unambiguous, arguments are typed, and failures teach the agent its next move. Same model, a reliable agent — because the tools became usable.
This is the reading. The interactive version — active-recall quiz, a hands-on experiment you run in your own AI, and an earned mastery check — is free in the app.
Start this lesson free →