Tool Design Is the Product

The first agent I shipped that actually held up in production did so because I deleted half its tools and rewrote the rest. Not because I swapped the model. Not because I rewrote the system prompt for the fourth time. The model was the same. The prompt got shorter. What changed was the shape of the tools.

I think most teams have the leverage backwards. They obsess over which model, then over prompt phrasing, and treat tools as plumbing they bolt on at the end. In my experience the tools are the product. The model is a reasoning engine that can only act through the interface you hand it, and a bad interface caps the ceiling no matter how good the model gets.

A tool is an API for a non-deterministic caller

When I build an internal REST endpoint, the caller is code I wrote. It passes exactly the arguments I told it to. When I expose that same endpoint as an agent tool, the caller is a model that read a paragraph of description and is guessing. Those are not the same contract.

In the AI-native ERP I’m building (Vontra), the whole platform is operated through tool calls, and the early tools were thin wrappers over the database. update_record(table, id, fields). Elegant for me, lethal for the agent. The model would invent table names, pass a field that didn’t exist, or update the wrong record because nothing in the signature told it what was legal. Every call was a coin flip.

The fix was to stop designing tools for myself and start designing them for a caller that cannot read my mind:

• update_invoice_status(invoice_id, status) where status is a closed enum, not a free string.
• Names that describe the business action, not the storage mechanism.
• Return values that say what happened in plain language the model can reason over, not a raw row dump.

A tool the model can misuse is a tool the model will misuse. Constrain the surface and you remove whole classes of failure before they happen.

Granularity is the real decision

The hardest call is how big each tool should be. Too fine-grained and the agent drowns in a forty-step trajectory to do one thing, burning tokens and latency at every hop, accumulating chances to derail. Too coarse and the tool becomes a god-function with twelve optional parameters the model can never get right.

My rule now is: one tool should map to one decision a competent human operator would make in one move. On HANNA, the cold-call voice agent, I do not give the model set_field and save. I give it book_appointment(slot, contact). The booking either succeeds atomically or it doesn’t. The agent does not orchestrate a transaction. It expresses an intent, and my code handles the messy reliable part.

That split matters. The model is good at deciding what should happen. It is bad at the bookkeeping of making it happen reliably. Push the reliability into the tool implementation where deterministic code belongs.

Error messages are prompts you wrote in advance

Here is the part almost everyone skips. When a tool fails, the error text goes straight back into the context window and becomes part of the model’s next reasoning step. Your error message is a prompt. Treat it like one.

// Useless — the model has nothing to act on
{ "error": "ValidationError: 422" }

// Useful — tells the model exactly how to recover
{
  "error": "invoice_not_found",
  "detail": "No invoice with id 'INV-4821'. Use list_invoices to find valid ids.",
  "hint": "Did you mean to search by client name first?"
}

The second form turns a dead end into a recoverable step. I have watched the same model loop forever against a 422 and recover in one turn against a message that named the next action. The model is not stupid; it is starved. Feed it.

Fewer tools, sharper tools

There is a tax per tool that nobody puts on the invoice. Every tool definition sits in the context window on every single call. Twenty verbose tools can eat thousands of tokens before the model has read a word of the user’s actual request, and they crowd the model’s attention so it picks the wrong one more often.

Tools exposed	Selection accuracy	Tokens in definitions
8 focused	high	~1,200
25 overlapping	noticeably worse	~5,000
50+ “just in case”	poor, frequent wrong-tool	~11,000

Those numbers are illustrative of the shape I keep seeing, not a measurement from one run, but the direction is reliable: every tool you add makes every other tool harder to pick. When two tools overlap, the model dithers between them. I now treat adding a tool the way I treat adding a database index. There had better be a clear reason, because it is not free.

Design tools around the trajectory you want

The deeper move is to stop thinking tool-by-tool and start thinking about the path. If I want an agent in a federal-contractor intelligence platform I built to qualify a lead, the natural human path is: find the entity, pull its award history, check the point of contact, decide. So I shape tools that fall in that order, where each return value hands the model the input it needs for the next call. search_entity returns an id that get_award_history accepts. The interface itself nudges the model down the road I want it on.

That is the whole game. You are not just exposing capability. You are laying down rails. Choosing what is reachable in one move and what requires a detour is how you make a good trajectory the path of least resistance, the same way a planning-versus-reacting choice or a tight context window shapes everything downstream.

What I check before shipping a toolset

Before an agent goes near production I run its tools against a blunt list:

1. Could a careful human read the tool name and description and know exactly when to use it? If not, the model can’t either.
2. Are the dangerous, irreversible tools gated behind confirmation or a dry-run mode? Deleting and emailing are not the same risk class as reading.
3. Does every failure return a message that names the recovery move?
4. If I removed this tool, would the agent actually lose a capability, or just an option to get confused?

The model will keep getting better. That helps. But a better model pointed at a sloppy toolset just fails more confidently. The tools are where you encode judgment, constraints, and the shape of correct behavior. That is not plumbing. That is the product, and it is the one part of the stack you fully control. Build it like it matters, because the next ten times your agent surprises you, the tool definitions will be where you go to fix it.