2.2 Structured Error Responses

Tools fail — networks time out, inputs are malformed, policies forbid an action. The question Task Statement 2.2 asks is: when a tool fails, what should it tell the agent? And the answer matters more than you'd think, because the agent has to DECIDE what to do next based purely on what the error says.

Imagine you ask an assistant to book a flight and they come back with just: "It didn't work." What now? Should they try again? Try a different airline? Give up and ask you? They — and you — have no idea, because 'it didn't work' contains no information to act on. Now imagine instead: "The airline's site timed out; this usually clears up in a minute — shall I retry?" That tells you exactly what happened and what to do. The difference between those two messages is the difference between an agent that recovers gracefully and one that flails.

That's the core insight: a generic error like "Operation failed" gives the model nothing to reason with, so it can't make a good recovery decision. A STRUCTURED error — one that says what kind of failure this is and whether retrying makes sense — lets the agent respond intelligently. This lesson is about designing those structured errors.

Not all failures are the same, and the right response depends on the KIND. There are four categories worth distinguishing, and the key thing each tells you is whether retrying could possibly help.

Why does this matter so much? Because an agent that can't tell these apart wastes effort and frustrates users. If it retries a business error ('refund denied by policy') ten times, it never succeeds and looks broken. If it gives up on a transient timeout that a single retry would have fixed, it fails unnecessarily. Encoding the category — and an explicit isRetryable flag — lets the agent skip the pointless retries and pursue the ones that can work.

Now the single most-tested idea in 2.2, and it's a subtle one. There's a world of difference between 'I couldn't run the search' and 'I ran the search and found nothing' — but a careless tool reports both the same way, and that causes the agent to behave badly.

Picture a search tool. Case one: the search service was unreachable — an ACCESS FAILURE. The agent genuinely doesn't know the answer; retrying might help. Case two: the search ran perfectly and returned zero matches — a VALID EMPTY RESULT. 'No matches' IS the answer; retrying is pointless and will just return zero again. In MCP terms, the access failure sets isError: true (something went wrong), while the valid empty result sets isError: false with a result count of zero (nothing went wrong — there simply are no matches).

If a tool collapses these two into one ambiguous response, the agent can't tell them apart, and it does the wrong thing — most commonly, it RETRIES a query that genuinely has no results, over and over, as if the empty result were a failure. Designing the tool to clearly signal which case it is — failure versus legitimately empty — is what keeps the agent from chasing answers that aren't there.

Structured errors matter even more once you have the multi-agent systems from Domain 1, because now errors have to travel between agents without losing meaning. The pattern combines two ideas you've already met: local recovery and structured propagation.

First, LOCAL recovery: a subagent should handle transient failures itself — retry that timeout locally before bothering the coordinator. There's no reason to escalate a hiccup the subagent can fix on its own. Second, structured PROPAGATION: when a subagent hits a failure it genuinely can't resolve, it shouldn't just die or return an empty result pretending success. It should propagate UP to the coordinator a structured report — the failure category, what it was attempting, and any partial results it managed to gather before failing — so the coordinator can decide intelligently: retry with a different approach, proceed with partial data, or note the gap. (This connects directly to Domain 5.3, error propagation.)

The anti-pattern here is the silent failure: a subagent catches an error and returns {results: [], status: 'success'}, hiding the problem. The coordinator then thinks everything is fine and produces a confidently incomplete result — the same family of bug as the narrow-decomposition failure from Lesson 1.2, but caused by swallowed errors instead.

The 2.2 traps cluster around two confusions: treating all errors the same, and confusing a failure with a legitimately empty result. Keep the four categories and the failure-vs-empty distinction sharp and they fall away.

• •Retrying an empty result. ✗ Treating 'zero matches' as a failure and retrying. ✓ A valid empty result (isError:false, count 0) IS the answer — don't retry.
• •Generic error messages. ✗ Returning 'Operation failed' with no structure. ✓ Return category + isRetryable + a readable description so the agent can decide.
• •Retrying business errors. ✗ Retrying a policy violation as if it were transient. ✓ Business and permission errors are not retryable — explain or escalate.
• •Silent suppression. ✗ A subagent returning empty results marked 'success' on a timeout. ✓ Propagate a structured error with partial results so the coordinator sees the gap.

You now know why generic errors fail an agent, the four failure categories, the all-important failure-vs-empty distinction, and how errors should flow through a multi-agent system. The exercise has you build tools that fail INFORMATIVELY and watch the agent's behaviour change as a result.

Good descriptions get the right tool called (2.1); structured errors let the agent recover when a tool fails (2.2). The next lesson, 2.3, steps back to the fleet level: how many tools an agent should have, and how to control which tool it's allowed — or forced — to call.