Recovery Guide

# Recovery Guide

Provide actionable error messages that tell agents how to fix the problem.

## Category
Tool Resilience

## Context
Any tool that can fail.

## Problem
Generic error messages don't help agents recover.

## Solution
Guide recovery explicitly:
- **What went wrong**: Clear description
- **Why it failed**: Root cause
- **How to fix**: Specific next steps
- **Alternative tools**: What else to try

## Example (Python)
```python
@tool
def send_message(
    recipient: str,
    message: str
) -> SendResult:
    """Send a message to a user."""
    try:
        user = resolve_user(recipient)
        if not user:
            raise RecoverableError(
                error="User not found",
                reason=f"No user matches '{recipient}'",
                recovery_steps=[
                    f"Try search_users('{recipient}') to find similar users",
                    "Check spelling of the recipient name",
                    "Try using email address instead of name"
                ],
                suggestions=fuzzy_match_users(recipient)
            )
        return _send(user.id, message)
    except RateLimitError:
        raise RecoverableError(
            error="Rate limited",
            recovery_steps=["Wait 60 seconds and retry"],
            retry_after_seconds=60
        )
```

## Considerations
- Be specific about what to do next
- Include concrete tool names and parameters
- Distinguish retryable from permanent failures

## Related Patterns
- error-classification
- fuzzy-match-threshold
- dependency-hint

---
Source: https://arcade.dev/patterns/recovery-guide