Idempotency prevents repeated execution of one intent from producing multiple effects when supported by the operation’s contract. It does not apply indiscriminately to every tool.
01STORY BRIEFThe idea in three screens.3 SCREENS
Retry without ordering twice.
Idempotency prevents repeated execution of one intent from producing multiple effects when supported by the operation’s contract.
After a timeout, do not assume nothing happened. Check state or reuse the same key for the same intent when supported. TokPortal documentation excludes some secret-bearing operations from replay. A fresh key on every retry defeats the protection you wanted.
Document what the application considers the same intent. Retrying after a lost response is not a new order; changing country or content may be. Make that distinction visible in the log. It prevents both costly duplicates and ambiguous replays after parameters change. When the service’s contract is unclear, inspect state before retrying rather than treating every timeout as proof of failure.
A timeout is not permission to duplicate the action
When a request times out, the client knows that it did not receive a timely answer. It may not know whether the server completed the operation. Retrying a purchase or publication as a brand-new action can therefore create a duplicate. Where the service supports idempotency, use a stable key for one logical operation and preserve it across retries of that same request. Read the service's documented scope and retention rules; support for a key is not a universal promise that every endpoint behaves identically.
Three states, not a binary guess
- 01Confirmed
The service returned a verifiable result.
- 02Rejected
The service explicitly declined the operation.
- 03Unknown
Reconcile before issuing a potentially duplicate action.
Editorial model: a way to reason about the process, not measured platform results.
Store the operation's inputs, key and returned identifiers in durable state. Before retrying an uncertain result, query status or reconcile against the known identifier where the API permits it. Changing the payload while reusing the same key can also be incorrect, so treat a revised action as a separate reviewed operation. Expose an unknown state instead of collapsing it into failed. The operator needs to know when investigation is safer than another click. Reliability often comes from resisting an immediate retry, not from adding more retry loops.
“Retry without ordering twice.”
02FIELD KITFrom concept to practice.2 SCREENS
Keep one key per logical intent.
Adapt this to your audience, budget and test scope.
Put it to work.
- 01Keep one key per logical intent.
- 02Review documented exceptions.
Notes & sources.
The limit. Reusing a key for a different request can create contract ambiguity.
- developers.tokportal.com/mcp/ · consulted September 8, 2026
THE ORGANIC CLUB is an editorial project initiated by TokPortal. That relationship is separate from the evidence behind claims. Editorial signatures and image credits are explained in our policy. Our editorial policy →
