eldermoraes.com

November 20, 2026

Agent tool calls and idempotency keys: what one has to do with the other

Vishnuvardhan Reddy Kaithapuram builds AI agents at Amazon Advertising. The tools of the agent he works on sit behind MCP (Model Context Protocol) servers, and the services around it are written in Java. In an article published on Foojay on November 19, he says the failures that took most of his time did not come from the model. They came from a tool call that ran twice.

Anyone who works on Java backends has seen this problem before. Clients that retry requests have always existed, and the usual answer, the idempotency key, works for agents too. The part that needs care is deciding what the key identifies and where in the code it is created.

The sequence he describes is simple. The agent asks the tool to make a change, the change happens, but the response is slow. The caller records a timeout and the runtime tries again. As he puts it, a timeout tells you nothing about whether the work happened. The same thing happens when a queue delivers a message more than once, or when the connection drops right after the server finishes the work. The model takes no part in any of these decisions, so no instruction in the prompt prevents the repetition. The one that decides whether a retry is safe is the service that implements the tool.

This reminds me of the saga pattern. It was described in a 1987 paper, for long-lived transactions in databases, caused quite a stir when it reached microservices, and now shows up again in agent systems. The topology changes, and the distributed systems problems stay the same. A duplicated tool call is one of those problems, and the agent is just one more client that retries requests.

The MCP specification defines the idempotentHint annotation, which says that calling the tool several times with the same arguments has no additional effect. But the same specification warns that these annotations are hints and may not faithfully describe the tool’s behavior. The guarantee still lives in the service code.

In the code, the first thing to get right is what the key identifies. A new key on every attempt, Kaithapuram says, is useless, because every retry arrives looking like a new request. The key has to identify the logical operation, which he builds from the step making the call, the tool, the arguments and an identifier for that step’s execution. In Java, the difference looks like this:

// New key on every attempt: every retry becomes a new operation
UUID keyPerAttempt = UUID.randomUUID();

// Key derived from the logical operation: every retry gets the same key
UUID keyPerOperation = UUID.nameUUIDFromBytes(
        (step + "|" + executionId + "|" + tool + "|" + argumentsJson)
                .getBytes(StandardCharsets.UTF_8));

randomUUID() draws a different value on every call. nameUUIDFromBytes() always returns the same UUID for the same bytes. That is why argumentsJson has to be serialized with the fields always in the same order, otherwise the same request produces different bytes and the key changes.

The executionId prevents the opposite mistake, which is skipping a call that should run. It is assigned when the step is planned and stays the same across all retries of that step. If the same step runs again on purpose, with the same arguments, it gets a new executionId. Without this field, a legitimate repeat would return the stored result of the first execution and the tool would never run.

Where the key is created matters as much as what goes into it. The key has to be born in the step that plans the call, because that is where the logical operation is known. Created in the transport layer, it changes on every retry, because the transport cannot tell one logical request from another. It is the same reasoning I apply to compensation in agent systems: it has to live in the framework, because the infrastructure is too far from the agent’s context.

On the service side, checking the key before executing is not enough. Two concurrent calls may both find nothing and run the tool at the same time. Kaithapuram solves this with a conditional write in DynamoDB: only the call that manages to reserve the key runs the tool, and the other one waits for the result. The reservation has an expiry, so that a retry can take over if the one holding it stops before saving the result. In a Java service with a relational database, a unique constraint on the key column does the reservation, and a conditional UPDATE lets the retry take over an expired reservation.

Where to start? With the tools that write. A repeated read costs a bit of processing. A repeated write leaves a duplicate record that someone will have to find and undo by hand. Give every write call a key, keep the result for longer than a retry can take to arrive (for him, one day is enough) and log the key on every call. When a response comes out wrong, that log shows whether the tool ran and how many times.

For a Java team, none of this needs a new library. It is the same idempotency key Java services have used for years with any client that retries requests.

References