The agent had six tools. One of them, get_contact, hit an internal API. The API returned 200 OK with a body of {} whenever the contact ID didn't exist. No error, no null, just an empty object. The agent read that as "this contact exists and has no fields", filled in the blanks from the conversation context, and wrote the result to the CRM.

The model was doing exactly what it should. It was handed a tool that lied, and it believed it.

Make silence impossible

When I audit a tool layer, the first thing I look for is what happens on the boring failure paths: not found, unauthorised, rate limited, timed out, returned the wrong shape. If any of those come back as a successful empty result, the agent has no way to distinguish "nothing there" from "I got nothing useful".

The fix in that codebase was about twenty lines. Every tool response got an explicit envelope:

{
  "status": "not_found",
  "message": "No contact with id 4821",
  "retryable": false
}

status is required. The wrapper throws if a tool returns anything else, which means a bad tool fails at the boundary rather than three steps later inside the model's reasoning. Suddenly the agent stops inventing contacts and starts telling the user the record doesn't exist. Which is the correct behaviour, and it took less time to fix than writing the ticket.

Errors are instructions

There's a second benefit that people miss: a well-written error is the cheapest prompt you will ever write.

"Rate limited, retry after 30 seconds" is a better instruction than anything you can put in a system prompt. "The user is not authorised to view billing: ask them to confirm the account owner" tells the agent exactly what to do next. Compare that to a generic 500 and you can see why agents thrash.

I write tool errors for the model as the primary reader, not the developer. Developers get the stack trace in the logs. The model gets a short, actionable sentence.

Assertions before the call, not after

The other half is input validation. If update_record requires an account_id, reject the call when it's missing instead of letting the database insert a row with a null and discovering it in a reconciliation report a week later.

This is unglamorous schema work. It is also the single highest-leverage change I make in most codebases. Typed tool inputs and explicit status codes turn a class of flaky, hard-to-reproduce agent bugs into loud, immediate, obvious ones.

What to do on Monday

• Pick your five most-used tools.
• For each one, write down every way it can fail. All of them, including the ones that "can't happen".
• Make each failure return a distinct, human-readable status.
• Throw on anything unrecognised rather than passing it through.
• Add a test that calls the tool with a bad ID and asserts the agent reports a problem instead of inventing an answer.

That last test is the one that catches regressions, because someone will "helpfully" make the API return a default again in six months.

The prompt matters. But in my experience, a mediocre prompt on top of honest tools beats a beautiful prompt on top of tools that lie.

That's not caution for its own sake. Without a measurement, prompt changes become a kind of office folklore. Someone tweaks the system prompt because a support ticket mentioned a weird answer, the fix quietly breaks four other cases, and nobody finds out for a month.

Start with thirty real examples

Not synthetic ones. Real inputs, copied from the actual source: real emails, real documents, real questions people have asked. Synthetic test data is written by the same brain that wrote the prompt, so it tests the same assumptions.

I aim for around thirty to start. If a task has obvious categories, I spread them across the categories rather than picking thirty variations of the easy case. Half a day of work, usually less, because the client already has the material.

Each example gets:

• The input, unchanged apart from removing anything identifying.
• What a good answer looks like, in prose. Not a score, an actual answer.
• A short note on what would make a response unacceptable.

Grade the shape, not just the wording

Anyone who has tried to match model output to an exact string knows it fails on a trivial rewrite. So I check two layers separately.

The first is deterministic: did it call the right tool, in the right order, with valid arguments? Did it include the required fields? Did it refuse where it should have refused? These are assertions, and they either pass or they don't.

The second layer is judgement, and I use a model to grade it against the reference answer with a strict rubric: does the response contain every required fact, does it contradict the source, does it invent anything. Model grading is imperfect, which is exactly why it's the second layer and not the first.

The number that matters is the delta

Nobody should care whether a run scores 82% or 86% in the abstract. The useful signal is directional and comparative:

Last week's prompt scored 24 of 30. This week's scores 29. It also costs 40% less because it stops after three tool calls instead of seven.

That sentence is what lets you ship a change with confidence, and it's what stops a well-meaning edit from shipping blind.

Wire it to the commit

An evaluation set that lives in a notebook is decoration. It belongs in CI, running on the paths that touch prompts, retrieval configuration or tool definitions. It doesn't need to block every pull request, but it should make a regression visible within minutes rather than during a customer call.

I keep a short failure log too, one line per real-world failure, appended as it happens. Those lines become the next ten test cases, and they're worth more than anything I could invent.

The uncomfortable part

Writing the evaluation set forces a conversation about what "good" actually means. Teams often disagree about this and didn't know it. One person thinks a shorter answer is better, another wants the full audit trail. Better to find that out in an afternoon of writing test cases than three weeks into a build.

If you take one thing from this: the evaluation set is not a quality gate you add at the end. It's the specification. Write it early, and the rest of the project gets noticeably less vague.

Here's the shape of the last three systems I costed out.

The model calls are predictable

A typical agent run in the systems I build makes somewhere between six and twenty model calls. With a mid-tier model, sensible context management and a prompt cache, that lands in the low single-digit cents per run. Even at a few thousand runs a month, you're talking about a line item that doesn't threaten anyone's budget.

The exception is when something goes wrong in a loop. Which brings me to the actual problem.

Retries are where the money goes

One system I reviewed was spending four figures a month on a workflow that should have cost about eighty dollars. The agent was calling a flaky internal endpoint. When it failed, the tool returned generic error text, and the agent decided a sensible next step was to try again. Sometimes it tried again in a slightly different way. Occasionally it tried eleven times.

Watch out for:

• Retry storms. No cap on attempts, no backoff, no budget check.
• Loop drift. The agent re-plans because it can't tell whether the last step succeeded, so it redoes work it already paid for.
• Re-read everything. Passing the full conversation and all retrieved documents on every call, so the same 40,000 tokens get billed twenty times.

That last one is the most common. Trimming context to what the current step actually needs is normally a 50 to 70% cost reduction with no quality loss, and it's a few hours of work.

The real cost is the human time

Then there's what never appears on the invoice: the person who checks the output.

If your agent produces work that someone has to read carefully before trusting, you haven't removed the task, you've moved it. And reading someone else's work critically is often slower than doing it yourself. I've watched teams celebrate a 70% time saving that didn't exist.

The honest question is not "how much does the agent cost to run?" It's "how much of a human's attention does it still require?" If the answer is "the same as before, but now with a review queue", the project hasn't landed yet.

Ways I've seen that fixed:

• Move the approval gate so it only catches the risky 10%, not every run.
• Make the output verifiable in seconds: cite the exact source line, show a diff, put the numbers in a table instead of prose.
• Route simple cases straight through and hold only the ambiguous ones.

What I do now

Every agent I ship has three ceilings and one report:

1. A max steps limit per run, after which it stops and asks.
2. A spend cap per run and per day, enforced in code rather than trusted to the prompt.
3. A context budget for each step, with retrieval scoped to that step.
4. A weekly line in the logs: runs, failures, average steps, average cost, and how many needed a human to intervene.

Those four numbers tell you whether the system is healthy far better than watching the model bill. The token cost is a symptom. Steps, retries and human intervention are the disease.