Structured Failures and Retry Decisions
Explore how to write structured error strings for tools to provide Claude actionable failure information. Understand four key failure categories and why clear error signaling prevents silent degradation and false outputs. Learn to apply the data_gaps pattern for robust multi-agent failure propagation and improve reliability in AI system orchestration.
In the previous lesson, we focused on the tool description as the mechanism for shaping when and how Claude calls a tool. This lesson covers what happens after the call: what the tool returns when something goes wrong and how that return value determines whether Claude can recover gracefully or is left guessing.
A tool that returns None, an empty string, or a raw Python exception message on failure is not giving Claude anything to work with. A tool that returns a structured error string tells Claude exactly what failed, why, and what the agent should do next. The difference between these two behaviors is the difference between a loop that degrades silently and a loop that reports gaps correctly. By the end of this lesson, we will be able to:
Identify the four failure categories that tool return values must cover
Write structured error strings that give Claude actionable information for each failure type
Explain why
Noneand the empty string are dangerous return values for tool failuresApply the
data_gapspattern for propagating failures through multi-agent systems
Why return values for failure matter
When Claude receives a tool result, it reads the content string and decides what to do next. That decision is only as good as the information in the string.
Consider a tool that retrieves a customer's billing history. Three different things could go wrong: ...