Tool Failure Handling

Tools fail. Design the failure first, the success second.

A schema that's clean and a tool that's "fast on the happy path" still produces a broken agent if the failure semantics are wrong. The most common production failure isn't a bug in the tool — it's the agent retrying, compensating, or proceeding under the wrong assumption about whether the call took effect.

When to use this skill

• The user is adding a tool to an agent that calls external systems (APIs, databases, queues).
• The user reports duplicate side effects (charged twice, emailed twice, ticket created twice).
• The user reports the agent hanging on a slow tool, or looping retries forever.
• The user is choosing between framework-level retry policies and per-tool semantics.

Classify the call first

The right retry / recovery policy depends on what the tool does. Classify before designing: