Tool use patterns
Tools as the agent's hands: what makes a good tool, the read/write/compute taxonomy, and designing tool sets the model can actually wield.
A tool is a function you expose to the model: a name, a description, a typed input schema, and your code that runs when the model calls it. The model never executes anything — it requests; your code executes and returns results. That separation is the safety foundation everything else builds on. And tool design — not prompting — is where agent quality is mostly won.
The taxonomy that drives every safety decision
- Read tools —
lookup_order,search_docs,get_ticket. Safe to call freely; worst case is wasted tokens. Agents should be rich in these: most bad actions start as missing information. - Compute tools —
calculate,run_code. Transform without touching the world; safe if sandboxed (Module 3). - Write tools —
update_ticket,send_reply,issue_refund. Change reality. Every write tool gets a stakes rating, and stakes decide its autonomy dial: free / gated / propose-only (Module 5).
What makes a tool good (the model is your user)
- The description is a prompt. It's how the model decides when to use the tool and how to fill its arguments. 'Look up an order by its ID (format HL-####). Returns items, status, dates, totals. Use before any refund decision.' beats 'gets order data' by an order of magnitude.
- One clear job per tool.
handle_customer_stuff(action, ...)with seven modes forces the model to learn your internal dispatch; seven small tools let it think in actions. Err toward more, narrower tools. - Typed, constrained inputs. Enums for categories, patterns for IDs, required vs. optional — the same schema discipline from Prompt Engineering, now on the input side. Every constraint you encode is an error class the model can't commit.
- Errors that teach. A tool returning
{"error": "order not found"}invites a retry loop; returning{"error": "order HL-9999 not found — IDs appear in the ticket text; re-read it or ask the customer"}teaches the next step. Agents recover exactly as well as their error messages allow. - Return structure, not prose. JSON the model can reason over; include only fields it needs (every tool result burns context — Module 4 problem, Module 1 habit).
I'm designing tools for an agent that resolves customer-support cases for a retailer. Here are the actions a human agent takes: [look up orders, check return/refund policy, calculate refund amounts, update the ticket with notes and status, send a reply, escalate to a supervisor, issue refunds up to a limit]. Design the tool set: names, one-sentence descriptions written FOR the model, input schemas with constraints, read/compute/write classification, and a stakes rating (low/medium/high) per write tool.
Compare its design to the one you'll build in the lab. Models are good tool designers when told the user is a model — and critiquing its choices is the fastest way to sharpen your own.
When an agent lacks a tool it needs, it doesn't stop — it improvises: guesses the policy instead of checking, computes refunds in its head instead of precisely. Audit for gaps by walking real tasks: every fact a human would look up and every action they'd take needs either a tool or an explicit 'escalate' path. An agent's tool list is its honesty boundary.