Tool Errors the Model Can See
Return errors the AI can read and recover from.
Tool Errors the Model Can See is a free MCP Academy lesson on CoddyKit — lesson 1 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.
Errors Are Just More Context
When a tool fails, the AI does not crash. It simply reads your error as context and decides what to do next, just like any result.
A Good Error Is Actionable
Write the error for a reader who can act on it. City not found beats Exception, because the model can ask the user to fix the city.
Return an Error String
The simplest pattern is returning a clear message string when something is wrong, so the model reads exactly what failed.
@mcp.tool()
def get_user(uid: int) -> str:
if uid < 1:
return "Error: uid must be positive."Raise to Flag a Tool Error
You can also raise a normal Python exception. FastMCP catches it and reports a tool error back to the model, not a server crash.
@mcp.tool()
def divide(a: float, b: float) -> float:
if b == 0:
raise ValueError("b cannot be zero")
return a / bisError Marks the Result
Under the hood, a failed tool call returns content with isError set true. That flag tells the client this result describes a failure.
The Model Can Recover
A readable error lets the AI retry with better input or explain the issue to the user, turning a failure into a helpful next step. 🔁
Say What and Why
Good errors name what failed and why. File missing: report.csv is far more useful to the model than a bare Not found.
Suggest a Fix
When you can, hint at the remedy inside the error. Date must be YYYY-MM-DD lets the model correct itself on the very next call.
if not iso_date:
raise ValueError("Date must be in YYYY-MM-DD format")Never Leak Internals
Errors reach the model and often the user, so keep secrets, raw stack traces, and connection strings out of the message you return.
Validate, Then Error Early
Check arguments first and return the error before doing real work. Failing fast keeps your tool predictable and easy to reason about.
Errors Are Part of the Contract
Treat failures as designed output. A tool that names its likely errors is as useful to the model as one that documents its success.
Quick Check
Why write tool errors as clear, readable messages?
Recap
Tool errors are context the model reads: make them clear, say what and why, suggest a fix, and never leak internals. ✅
Frequently asked questions
Is the “Tool Errors the Model Can See” lesson free?
Yes — the full text of “Tool Errors the Model Can See” 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 “Tool Errors the Model Can See”?
Return errors the AI can read and recover from. 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 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Tool Errors the Model Can See” 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
- Tool Errors the Model Can See
- Protocol Errors vs Tool Failures
- Validate Inputs Before Acting
- Fail Safely, Never Hang