Guide

Agent tool-call idempotency: stop duplicate side effects

Use an application-owned operation ledger and idempotency key for side-effecting tools. A model-generated tool-call ID helps correlate one response; it does not guarantee that a retried conversation will not request the same business action again.

Automatic retries and parallel tool calls are useful until the tool creates a real-world effect. The relevant unit of deduplication is the intended operation, not the network attempt that happened to request it.

What the documentation establishes

OpenAI function calling describes a loop in which the model proposes calls and the application executes them. It also documents parallel-call controls on supported models. Authorization and durable execution semantics remain application concerns; disabling parallel calls alone cannot prevent duplicates across retries.

Decision worksheet

Operation ledger states
StateMeaningAllowed recovery
ProposedValidated but not authorizedRequest approval or reject
AuthorizedExact operation approvedAttempt once under a stable key
ExecutingOutcome may be ambiguousQuery downstream status
CommittedResult is durableReturn the recorded result
Failed safelyNo side effect establishedRetry under the operation policy

How to test your implementation

  1. Derive an operation ID from trusted task state, actor, action and normalized business arguments. Do not let untrusted retrieved text choose the deduplication boundary.
  2. Persist authorization and the operation record before invoking a write tool. Bind approval to the exact recipient, amount or resource.
  3. Force a timeout after the downstream write succeeds but before the agent receives the result. Recovery should retrieve the existing outcome.
  4. Replay the same business intent with a different model tool-call ID. Confirm it does not bypass duplicate protection.
  5. Test parallel proposals for the same operation and legitimate repeated operations that need distinct IDs. A key that is too broad can suppress valid work.

Worked example

Hypothetical refund: task T approves refund R for order O and amount A. The payment service executes R, but the tool response is lost. The agent asks again with a new call ID. The ledger maps the repeated approved operation to R and returns the saved result instead of issuing another refund. If the amount changes, it is a new proposed operation requiring fresh authorization, not an automatic retry.

When to proceed—and when to stop

Prefer downstream services with explicit idempotency support and status lookup. Where those are absent, use narrow transaction boundaries and an operator reconciliation queue for ambiguous outcomes. Do not advertise exactly-once execution merely because your gateway retries once. Distributed failures can leave the caller uncertain even when the side effect has happened.

Evidence scope and maintenance

Source review: October 6, 2026. This is a documentation-led engineering guide, not a hands-on certification of every gateway. Provider examples establish only the behavior described in the cited API documentation. Worksheets and test procedures are GatewayScore editorial recommendations; numerical examples are hypothetical unless explicitly attributed. Retest whenever a tool gains a write capability, downstream idempotency changes or parallel execution is enabled.

Continue with Retries and failover, Coding agents through gateways. Use the model directory to inspect provider-listed options, then verify the exact endpoint and account terms.

Sources reviewed

Common questions

Is a tool-call ID an idempotency key?

Not automatically. It identifies a model call in a protocol; a business operation may be proposed again with a different ID.

Should every read tool use this ledger?

Read-only operations can often use simpler retries, but verify they truly have no side effects such as charging, notification or audit mutation.

Sources and editorial review dates are recorded with this guide. Catalogue-backed blocks use the dated catalogue snapshot. See our methodology.