Structured Failures and Retry Decisions

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 None and the empty string are dangerous return values for tool failures

• Apply the data_gaps pattern 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: ...