Idempotent tool calling: letting agents act without duplicating work
Models retry, repeat and misread. Here is how to make state-changing tool calls safe when they do.
Key takeaways
- Treat every tool as an API with strict schemas, validation and least-privilege credentials.
- Give state-changing tools idempotency keys so a repeated call is harmless.
- Start with read-only tools and add writes one at a time.
When an agent can call tools, mistakes stop being words and start being actions: a second order, a duplicate email, a deleted record. The defence is ordinary software engineering applied carefully to the tool layer.
Why duplicates happen
An agent may call the same tool twice because the first call timed out and it did not see a result, because the model lost track of its own history, or because a framework retried a failed step. Network failures and user retries add more paths to the same outcome.
Idempotency keys
An idempotent operation produces the same result however many times it is applied. For a state-changing tool such as "create order" or "send invoice", accept a client-generated idempotency key. The server records the key with the result; a repeat call with the same key returns the stored result instead of acting again. Derive the key from the task and the step, not from a random value created inside the model call.
Schema-first tools
- Define inputs and outputs with strict types and enumerations, and reject anything else before executing.
- Keep tools narrow: "refund_order(order_id, amount, reason)" rather than "run_sql".
- Return structured errors that tell the model what to fix, such as "amount exceeds order total".
Least privilege
An agent should act with the permissions of the user it serves and the task it is doing, not with a broad service account. Scope credentials per tool, log which identity made each call and make high-impact tools require approval.
Confirmation for the irreversible
For actions that cannot be undone, such as external messages or deletions, require explicit confirmation from the user or a reviewer. The agent drafts; a person approves.
Test tools without a model
Because tools are ordinary code, test them like code: unit tests for validation, tests for repeated calls with the same key, and tests for permission failures. Then test the model's tool selection separately on a set of representative requests.
Read first, write later
Many agents deliver most of their value with read-only access: finding, summarising and drafting. Add write tools deliberately, one at a time, with monitoring, once the read-only version has earned trust.
Details of our approach are on the tool calling and API actions page.