Idempotent Operation

# Idempotent Operation

Make operations safe to retry with identical results.

## Category
Tool Execution

## Context
Operations that may be retried due to failures or uncertainty.

## Problem
Network failures and agent retries can cause duplicate operations.

## Solution
Design for idempotency:
- **Idempotency key**: Client-provided unique identifier
- **Deduplication**: Detect and skip duplicates
- **Same result**: Return cached result for retries
- **Document behavior**: Explain retry safety

## Example (Python)
```python
@tool
def create_payment(
    amount: float,
    recipient: str,
    idempotency_key: str  # Client-provided unique key
) -> PaymentResult:
    """Create a payment. Safe to retry.
    
    The idempotency_key ensures duplicate calls return
    the same result without creating duplicate payments.
    """
    existing = payments.find_by_key(idempotency_key)
    if existing:
        return existing  # Return cached result
    return payments.create(amount, recipient, idempotency_key)
```

## Considerations
- Use natural keys (order_id) when available
- Cache results for the idempotency window
- Document the idempotency guarantee clearly

## Related Patterns
- command-tool
- error-classification
- recovery-guide

---
Source: https://arcade.dev/patterns/idempotent-operation