Structured Failures and Retry Decisions
Explore how structured error strings enhance tool integration by categorizing failures and providing Claude with actionable information. Learn to differentiate failure types, avoid ambiguous returns like None or empty strings, and apply error propagation patterns for reliable multi-agent systems. Understand why precise failure communication is vital for designing robust AI workflows.
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: ...