Errors That Teach

Who were error messages written for?

Every tool call can fail. And computing has fifty years of tradition about what to say when it does:

That design was correct for its world. The program that hit the error could only crash or retry blindly; the only reader who could act on an explanation arrived after the fact. Terse codes for the machine, searchable strings for the post-mortem human — that is what errors were for.

The receiver changed

An error returning into an agent's conversation lands somewhere no error has landed before: in front of an intelligent reader, mid-task, holding the full context of what it was trying to do — and occupying the user seat, where words steer. This reader can recover. But only if the error tells it how. Watch the same failure, written for each reader:

⟨tool_use⟩
book_room(room = "seminar", date = "2026-09-17", start = "14:00",
          end = "16:00")

⟨tool_result⟩
ERROR 409: CONFLICT

⟨tool_use⟩
book_room(room = "seminar", date = "2026-09-17", start = "14:00",
          end = "16:00")

⟨tool_result⟩
ERROR 409: CONFLICT

⟨tool_use⟩
book_room(room = "seminar", date = "2026-09-17", start = "14:00",
          end = "16:00")

⟨tool_result⟩
CONFLICT: seminar room is taken 13:00–15:00 on 2026-09-17
(research group meeting). Free 15:00 onward. Room "aud-2" (cap. 30)
is free 14:00–16:00. To book it:
book_room(room="aud-2", date="2026-09-17", start="14:00",
end="16:00").

⟨tool_use⟩
book_room(room = "aud-2", date = "2026-09-17", start = "14:00",
          end = "16:00")

⟨tool_result⟩
Booked: aud-2, 2026-09-17 14:00–16:00.

The recovery contract

What did the second error contain that the first didn't? Three things — and they are the whole design:

Every error is a turn in the conversation. Make it say:

WHAT   happened — precisely, in the terms the agent is working in
WHY    — the rule or state of the world that caused it
NEXT   — the best move from here, as concretely as code can make it

An error with WHAT alone is a report.
With WHY, it's an explanation.
With NEXT, it's a recovery.

Notice this is our closure principle, extended to the path we forgot: every successful result should hand the agent its next move — and every failure should too. A tool set with closure only on the happy path is a language where any stumble is a dead end.

Precompute the recovery

Here is the part almost everyone underuses. At the moment of failure, your code knows things — the valid values, the free time slots, the current state — with a certainty the model can never match. Don't describe the recovery. Compute it.

⟨tool_use⟩
log_expense(amount = 940, currency = "kr", date = "yesterday",
            category = "food")

⟨tool_result⟩
2 problems, both fixable:
· currency "kr" — this system uses ISO codes; you mean "NOK".
· date "yesterday" — must be absolute; today is 2026-09-18, so
  yesterday = "2026-09-17".
· category "food" is valid.
The corrected call:
log_expense(amount=940, currency="NOK", date="2026-09-17",
category="food")

⟨tool_use⟩
log_expense(amount = 940, currency = "NOK", date = "2026-09-17",
            category = "food")

A map from failures to recoveries

Failures are not all one kind, and each kind has a natural NEXT. This table is most of tool-error design:

Two rows deserve a closer look. The precondition row includes a pattern that connects to the library from earlier: an error can require the reading — "first use of this instrument: read its manual, then retry." Self-training on demand, enforced at the gate. And the not permitted row is richer than it looks:

⟨tool_use⟩
log_expense(amount = 2340, currency = "NOK", date = "2026-09-15",
            category = "client-meals")

⟨tool_result⟩
DENIED: client-meals limit is 500 kr per person; 4 attendees →
max 2000 kr. This is not final. Exceptions are granted for
client-facing events with a business justification. To request one:
1. the expense is parked as draft-8812;
2. call request_exception(expense_id="draft-8812",
   justification=<why this dinner served a business purpose>,
   approver="dept-head") — approvals usually within 2 days.

⟨tool_use⟩
request_exception(expense_id = "draft-8812", justification =
"Dinner with 3 representatives of the client following contract
negotiation; continuation of the working session.",
approver = "dept-head")

Fix the instance, or teach the rule?

One economic subtlety. Compare two errors for the same slip:

Remember the boundary, though: the model's weights are frozen. The rule is learned by the conversation, not by the model — the next conversation starts ignorant again, and its first slip buys the same lesson. That is not a flaw; it is the pricing. The rule costs nothing until a trajectory needs it, once per trajectory that does.