Idempotent Tool Calls for AI Agents: Retries Without Duplicate Work
Learn how to design agent tool calls so a retry never creates a second invoice, booking or message. Covers keys, state checks and unknown outcomes.

An idempotent tool call produces the same effect no matter how many times it runs with the same intent. For AI agents, this means a retry after a timeout, a restarted workflow or a repeated instruction should return the original result instead of issuing a second refund, booking or email. You get this by giving every side-effecting action a stable identity, recording its outcome before the agent reports success, and checking state before any write that cannot be undone.
Key takeaways
- Give each intended action a stable identifier built from business facts, created before the first attempt and reused on every retry.
- Record the outcome of every write in a place the tool layer can read before the agent reports success.
- Treat a timeout as an unknown outcome, not a failure. Look up the result by key before trying again.
- Enforce duplicate protection in the tool and the database, not in the system prompt.
- Keep approval boundaries on irreversible actions such as payments, bookings and outgoing messages, even when the tool is idempotent.
Why retries create duplicate work
An agent rarely fails the way a simple script fails. A tool call can succeed on the far side of a connection while the agent never receives the confirmation. The request times out, the orchestrator restarts the step, or an operator presses run again in a console. From the agent's point of view, nothing happened yet. From the booking system's point of view, a second appointment now exists.
There is a second source of duplicates that teams often miss. The model may plan the same action again after a long context, a summary or a changed instruction, and produce arguments that differ slightly from the first attempt: a new timestamp, a reworded memo, a different spelling of a customer name. Transport-level protection will not catch this, because the system sees what looks like a new request. The same intended action has to map to the same identity even when the wording changes.
Give every intended action a stable identity
Start with the business object, not the attempt. A refund is a refund for a specific charge and a stated reason. A booking is a specific customer, service and time slot. A reminder is a specific appointment, template and send window. The key is derived from those facts and stored with the request. A random identifier generated fresh on each attempt defeats the purpose, because every retry looks new to the receiving system.
Some providers already support this pattern. Stripe's documentation describes idempotency keys: the client sends a key with a request, and repeated requests with the same key return the result of the first one for a period the provider defines. Most internal systems do not offer this behavior, so your tool layer has to supply it.
- Derive the key from the facts that define the action, not from the time of the request.
- Include the action type, so a refund and a credit note for the same charge cannot collide by accident.
- Store a fingerprint of the normalized arguments with the key, so a reused key with different arguments is rejected instead of silently answered.
- Keep the key identical across retries, restarts and model re-plans.
For a deeper walk-through of this pattern in refund cases, see idempotent AI agent actions and double refunds.
Enforce it in the tool, not the prompt
Writing never send the same reminder twice into a system prompt is a request, not a control. Models follow instructions most of the time, and most of the time is not an acceptable standard for a payment. The guarantee belongs in the database and the tool: a unique constraint on the key, a conditional write that succeeds only once, or a lookup that runs before the external call.
Anthropic's guidance on writing tools for agents emphasizes that tool descriptions and return values shape how an agent behaves. Make the duplicate case explicit in the return value. When a tool finds a completed action under the same key, it should return that result with a clear status such as already processed, not an error that invites the agent to search for another route. The agent then has nothing to fix and no reason to improvise.
Handle the unknown outcome
The hardest case is the timeout. The agent sent the write, no confirmation arrived, and nobody knows whether the action happened. Treat that state as unknown. Resolve it by looking up the key in your own record and in the external system before anything else runs.
- If the write returned a clear success, store the result under the key and continue.
- If the write returned a final rejection, such as a closed account or an invalid service, record the reason, do not retry, and escalate.
- If the write timed out, look up the key. If the action exists, store its external identifier and continue. If it does not exist, retry once with the same key.
- If the lookup itself fails, stop the step, hold the request in a queue and notify the operator. Do not write again on a guess.
- If the action is irreversible and the outcome is still unclear after lookup, hand a person the key, the arguments and the relevant logs.
The broader rules for how many attempts an agent gets, and how long it waits between them, belong in a separate policy. The AI agent retry policy guide covers that layer.
Protect messages, bookings and webhooks
Messages need their own pattern because a sent email cannot be unsent. Write the intent to an outbox table with its key before calling the sending service. A separate sender reads pending rows, dispatches them, and records the provider's message identifier. If the sender crashes after dispatch but before recording, the row stays pending, and the lookup step should check the provider's records for the key before sending again. Where a provider cannot be queried by your key, the window cannot be closed completely, so reduce it and require human review for high-stakes messages.
Inbound events need the same discipline. Stripe's webhook documentation describes deliveries that can arrive more than once, so the receiving side should verify the signature and process each event identifier only once. An agent should record that an event was handled, rather than treating each delivery as a fresh instruction to act.
A repeated delivery should produce a recorded answer, not a second action.
Illustrative scenario: a small service business uses an agent to confirm appointments. The confirmation call times out after the booking was created. A naive retry books a second slot for the same visit. With a key built from customer, service and slot, the retry finds the first booking, returns its identifier, and the agent sends one confirmation message. The business sees one visit on the calendar and one message in the customer's history.
Checklist and how Be Human handles it
Before any write tool goes live, confirm the following for each one:
- The tool has a documented key and the fields that feed it.
- The key is enforced by a unique constraint, a conditional write or a provider mechanism.
- A repeated key returns the prior result with a clear status.
- Timeouts trigger a lookup, not a blind retry.
- Each outcome is stored with the key, the time and the external identifier.
- Irreversible actions have an approval boundary or a supervised period first.
- Test fixtures simulate a lost response and a duplicate delivery. The tool-call test fixtures approach lets you test the write path without touching live systems.
- Logs make duplicate attempts visible, so they can be counted and reviewed.
Be Human treats this as part of the operating design rather than a one-time fix. In a first engagement, the team defines the single role, the tools it needs, the keys for each write, the approval boundaries and the success criterion, including what a duplicate attempt looks like in the logs. In managed operations, the same work continues: permission reviews, monitoring of repeated keys and rejected arguments, and incident response when a duplicate slips through. Each change to a write tool is recorded so the business can read what changed and why.
If you are not sure which of your agent's actions deserves this treatment first, the free Be Human AI diagnostic is a practical way to find the first task worth handing to an agent.
Frequently asked questions
Is an idempotency key the same as a retry policy? No. A retry policy decides when and how often a step runs again, while an idempotency key decides whether a repeated run changes anything. You need both, because retries without keys multiply duplicate writes, and keys without a retry policy leave failed work stuck.
Do read-only tools need idempotency? Reads do not change state, so the duplicate risk is about cost and consistency rather than money or messages. Stable inputs still help, because they let the agent reason over the same data across attempts. Spend the most effort on tools that move money, create records or contact people.
Can my model provider or orchestration platform prevent duplicates for me? Those platforms can retry requests, but they cannot know what counts as a duplicate in your business. Two booking requests for the same customer might both be legitimate, and only your key definition captures that difference. The protection has to live in your tool layer, close to the systems that record the action.
How do I start if my systems do not support keys at all? Begin with the most costly write. Keep a local record of each action keyed by its business facts, add a lookup before the external call, and run the tool in a supervised mode until the duplicate checks hold under test. You can also start this week by writing down one action, the facts that define it and the key you would use.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


