Idempotent, Side-Effect-Aware Tools
Make repeated calls safe and predictable.
Idempotent, Side-Effect-Aware Tools is a free MCP Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Models May Call Twice
An AI client can retry a tool after a timeout or a dropped link. Your tool might run twice for what the user meant once.
What Idempotent Means
A tool is idempotent when calling it again with the same input changes nothing further. The second call is safely a no-op.
Reads Are Naturally Safe
Pure read tools, like fetching a record, are already idempotent. Repeating them just returns the same answer with no harm done.
@mcp.tool()
def get_user(id: int) -> dict:
return db.find(id)Writes Need Care
A tool that creates or charges money is dangerous to repeat. A blind retry could add a duplicate row or double a payment.
Use a Client-Supplied Key
Ask the caller for an idempotency key. If you have already processed that key, return the stored result instead of acting again.
if key in seen:
return seen[key]
seen[key] = do_work()Prefer Upsert Over Insert
An upsert writes or updates by a stable id, so running it twice leaves one row, not two. It folds retries into a single state.
INSERT ... ON CONFLICT (id)
DO UPDATE SET ...Declare Side Effects Clearly
Say in the tool description whether it mutates data. The model decides more wisely when it knows a call is destructive.
Separate Read and Write Tools
Keep a query tool and a mutation tool distinct rather than one that sometimes writes. Clear boundaries cut accidental changes.
Make Results Deterministic
Where you can, return the same output for the same input. Predictable results help clients cache and reason about your tool.
Check Before You Act
Before a write, confirm the target's current state. If the change is already applied, report success without redoing it.
if order.status == "shipped":
return "already shipped"Wrap Multi-Step Work in a Transaction
If a tool touches several rows, run them in one transaction. A retry then either fully applies or fully rolls back, never half.
Quick Check
Why does idempotency matter for an MCP tool that creates records?
Recap: Safe Repeats
Make writes idempotent with keys or upserts, declare side effects, split reads from writes, and use transactions. Next: versioning. ♻️
Frequently asked questions
Is the “Idempotent, Side-Effect-Aware Tools” lesson free?
Yes — the full text of “Idempotent, Side-Effect-Aware Tools” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Idempotent, Side-Effect-Aware Tools”?
Make repeated calls safe and predictable. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Idempotent, Side-Effect-Aware Tools” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Layered Server Architecture
- Config & Secrets via Environment
- Idempotent, Side-Effect-Aware Tools
- Versioning Tools & Schemas