Design Idempotent Agent Tools

Agent systems retry, users repeat requests, networks time out, and models occasionally invoke the same action twice. Mutation tools must assume duplicates happen.

Idempotency key

Generate a stable operation identifier for one intended action and pass it to the downstream service. Store the first result and return it for repeats.

Examples where this matters

• Sending email/SMS.
• Creating invoices.
• Payments/refunds.
• Deployments.
• Creating tickets.

Do not fake idempotency with “check then create”

Concurrent requests can race. Use a unique constraint, transactional record, or downstream idempotency primitive.