Aviral GargA tool call can time out while its server continues working. The assistant knows that it did not receive a response within its waiting window. It still needs evidence about whether the requested effect happened.
An original ticket example
Imagine an assistant asking a fictional service to create one support ticket. It records an operation ID and the intended ticket fields, sends the request, then loses the response. Creating another ticket immediately could duplicate the first one.
The operation is now unknown, rather than proved successful or unsuccessful. The next useful action is to find evidence about that same request.
AWS’s explanation of idempotent APIs describes this ambiguity when a resource-creation response is lost. Its approach uses a caller-provided request identifier so the service can recognize repeated requests for the same intent. The service’s handling of that identifier is the important guarantee.
Keep one identity for one intent
For our fictional ticket, an original recovery outline is:
- Keep the operation ID tied to the same intended ticket and unchanged fields.
- Use a supported, read-only lookup to find the operation result or resulting ticket, if the service provides one.
- If an authoritative result confirms creation, use that ticket instead of creating another.
- Retry only when the service’s documented idempotency contract permits it, using the required key and parameters within its supported window.
A lookup returning nothing may be incomplete or delayed. Its absence is useful only to the extent the documented lookup guarantees it. If the API offers neither a reliable lookup nor a suitable retry contract, preserve the unknown state for resolution instead of inventing a successful recovery.
Read the actual contract
Stripe’s API documentation illustrates the specificity required. For API v1, retries with the same key return the first saved response, including errors. Parameters must match. Keys can be pruned after at least 24 hours; reusing a pruned key creates a new request. Results are saved after endpoint execution begins.
Those are API-v1 rules from that provider, not a universal promise about every tool. Check which API version, operation, error and retention conditions apply before treating a retry as safe.
A local log improves auditability, but cannot make a remote ticket creation and a local success record atomic. The server could create the ticket just before the client crashes. Recovery still needs the external service’s evidence or contract.
Learning question: Why not generate a fresh key after every timeout?
Answer: A fresh key can make the retry look like a new operation. Preserve the original intent and follow the service’s contract.