Idempotency, partial success and safe retries

The property that decides whether retrying a tool is safe at all.

5 min read · Lesson 9 of 10 in this domain

Retry logic and idempotency are the same conversation. An operation is idempotent when performing it twice leaves the same state as performing it once — reading a record, setting a field to a value, deleting by id. An operation is not idempotent when repetition compounds — appending, incrementing, charging a card, sending a message. This matters because network failures are ambiguous: a timeout tells you the response was lost, not whether the work happened. Retrying a non-idempotent operation after a timeout can double-charge a customer. The standard remedy is an idempotency key supplied by the caller, so the server can recognise a repeat and return the original result instead of acting again.

• Idempotent: repeating leaves the same state. Reads, absolute sets, delete-by-id.
• Not idempotent: repeating compounds. Appends, increments, payments, sending messages.
• A timeout is ambiguous — it says the response was lost, not that the work failed. That is why blind retries are dangerous.
• Use a caller-supplied idempotency key so the server can detect a repeat and return the original outcome.
• Partial success needs its own representation: a batch tool that half-succeeds must report which items succeeded, not a single pass/fail.
• Report partial results as structured data, so the agent can retry only the failures rather than the whole operation.

Source: Claude Docs — Tool use overview · Independent study aid, not affiliated with or endorsed by Anthropic.