Repository navigation
Description
Preamble
Title: Input Validation Errors as Tool Execution Errors
Status: Draft
Author: @fredericbarthelet
Created: 2025-08-05
Abstract
This SEP proposes treating tools input validation errors as Tool Execution Errors rather than Protocol Errors. This change would enable language models to receive validation error feedback in their context window, allowing them to self-correct and successfully complete tasks without human intervention, significantly improving task completion rate.
Motivation
Language models can learn from tool input validation error messages and retry a tools/call with corrected parameters accordingly, but only if they receive the error feedback in their context window. Protocol Errors are catch at the application level by the MCP Client. Only Tool Execution Errors are forwarded back to the model as JSON-RPC responses. With the current specifications, models cannot see these error messages and thus cannot self-correct, leading to repeated failures and poor user experiences.
Problem Statement
Consider a flight booking tool that validates departure dates using the following zod validation schema:
departureDate: z
.string()
.regex(/^\d{2}\/\d{2}\/\d{4}$/, "date must be in dd/mm/yyyy format")
.superRefine((dateStr, ctx) => {
const date = parseDateFr(dateStr);
if (date.getTime() < Date.now()) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Dates must be in the future. Current date is " + formatDateFr(new Date()),
});
}
return true;
})
.describe("Departure date in dd/mm/yyyy format")Tool expected input JSON schema can only describe the regex statement. The actual programmatic check that the date is in the past cannot be expressed here as JSON schema.
Even when a model provides a syntactically correct date that passes JSON schema validation, there is no guarantee it will be in the future. When a validation error is raised and returned as a Protocol Error:
- The model doesn't receive the error message explaining why the date was rejected
- The model repeats the same mistake multiple times (e.g., Cursor typically consistently sends dates in 2024 when the user only specify day and month or relative date and repeats the same tools/call request 3 times without getting any information as to why the tools call fails)
- The task fails despite the model being capable of correcting itself if given proper feedback
- Users experience frustration and must manually intervene
Benefits of This Proposal
- Higher Task Completion Rates: Models can self-correct validation errors without human intervention
- Better User Experience: Reduced failures and faster task completion
- Leverages Model Capabilities: Modern LLMs excel at understanding and responding to error messages
- Reduced API Calls: Fewer retry attempts as models correct themselves on the first error
Specification
Current Behavior
The tool errors specification currently provides ambiguous guidance:
- "Invalid arguments" should be treated as Protocol Error
- "Invalid input data" should be treated as Tool Execution Error
This ambiguity leads to inconsistent implementations where valuable error feedback is lost.
Proposed Change
Clarify the specification with the following changes:
- Removes the "invalid argument" category from Protocol Errors.
- Tool Execution Errors should be used for all tool argument validation failures (merging
invalid argumentandinvalid input dataunder a newinput validation errorscategory)
Specification Text Changes
Update the error handling section to include:
## Error Handling
Tools use two error reporting mechanisms:
1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
- Unknown tools
- Server errors
2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
- API failures
- Input validation errors
- Business logic errors
Implementation
Before (Protocol Error)
// Model submits past date
request: {
...
method: "tools/call",
params: {
name: "book_flight",
arguments: {
departureDate: "12/12/2024" // Past date
}
}
}
// Server returns Protocol Error
response: {
...
error: {
code: -32602,
message: "Invalid params"
}
}
// Model retries blindly with another past date
// This cycle repeats until failureAfter (Tool Execution Error)
// Model submits past date
request: {
...
method: "tools/call",
params: {
name: "book_flight",
arguments: {
departureDate: "12/12/2024" // Past date
}
}
}
// Server returns Tool Execution Error (visible to model)
response: {
...
"result": {
"content": [
{
"type": "text",
"text": "Dates must be in the future. Current date is 08/08/2025"
}
],
"isError": true
}
}
// Model understands the error and corrects itself
request: {
method: "tools/call",
params: {
name: "book_flight",
arguments: {
departureDate: "12/12/2025" // Future date
}
}
}Backwards Compatibility
This change is backwards compatible as it:
- Does not alter the protocol structure
- Only clarifies existing ambiguous behavior
- Maintains all existing error types and formats
- Improves behavior without breaking existing implementations
Servers implementing the clarified behavior will provide better model self-recovery while continuing to work with all existing clients.
References
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsFinal
Activity
iwyrkore commentedon Sep 22, 2025
How can we get this change in the spec? Sure Claude is great at brute-force guessing but there are better ways.
fredericbarthelet commentedon Oct 1, 2025
Hey @domdomegg, as discussed together today, I just checked the SEP Guidelines and both Core Maintainer and Maintainer can sponsor SEPs.
If you still want to, I'd love to have your support on this proposal to include validation input error (and even more errors?) as MCP tool error in order to feed them back to the model.
Let me know what you think!
domdomegg commentedon Oct 3, 2025
I might be wrong, but I think clients MAY return all errors back to the model, including protocol errors. But it's up to the client.
I think in general this is the right move most of the time. Even if the MCP server itself is broken (protocol error) it's useful for the model to know that so it can approach a task a different way.
domdomegg commentedon Oct 3, 2025
I am happy to sponsor this SEP, and am supportive of it. I see it mainly as clarifying the documentation, rather than being a strict change to the specification (although appreciate others might see it differently - feedback welcomed!).
I have never sponsored a SEP before so I'll try to follow the instructions in the docs. Please shout if you need me to do something in particular, and don't assume I know what I'm doing better than you do 😉
domdomegg commentedon Oct 3, 2025
I think I am happy for this to go into
in-reviewactually, given how simple it is.Optionally you can raise a small PR to the docs (effectively the 'reference implementation') to make it more obvious, then we can move to
in-review? Or happy to move it now if you think we should just push it straight away.fredericbarthelet commentedon Oct 6, 2025
Happy to move to
in-reviewas well, thanks for your prompt response @domdomegg :)Just made a simple PR to update the doc: #1611
I also re-opened modelcontextprotocol/typescript-sdk#824, that can be used as reference implementation in TS SDK
3 remaining items
dsp-ant commentedon Nov 5, 2025
We are currently voting on this asynchronously in discord.
KKonstantinov commentedon Nov 7, 2025
Hi, this is a great improvement, and Python SDK and TS SDK are already having such a behavior, which will result in a
CallToolResultwithisError: truefor the following scenarios:The spec in the PR does not explicitly state what should happen whenever a
Disabled toolis called - unless we classify these underUnknown tools. The SDKs currently handle that as a CallToolResult/Tool Execution error. IfDisabled toolsfall under theUnknown toolscategory, should we explicitly state that?Existing SDK behavior (Python & TS)
The SEP in its current form would mean both SDKs would have to revert to a protocol-level error for Unknown tools and Disabled tools (in case these fall under the Unknown category as well).
In fact, Python SDK currently also wraps everything in a try/catch and converts any exception into a Tool Execution Error (see https://github.com/modelcontextprotocol/python-sdk/blob/9eae96a05e09fa3f35ea50f8b1c11b19c69f9597/src/mcp/server/lowlevel/server.py#L480)
Further points of clarification / existing SDK behavior / OutputSchema errors
The existing SDKs additionally return a Tool Execution Error in the following scenarios:
outputSchemadefined, but no structured output returnedoutputSchema, but generated an output that doesn't conform to it).Feel like this SEP, or an alternative one, could further clarify the standard on these scenarios, as they would currently be left for free interpretation?
Unknown tools / Disabled tools
FWIW, Unknown tools and disabled tools calls would still hold some value to return a Tool Execution error as opposed to a Protocol level error, for any tools that return other tool names to the model for execution etc. Further the ability to the model to know "this tool is missing" or "this tool was disabled" could be valuable, especially for older/less-sophisticated models.
Currently unsure what value it would bring to leave these as protocol-level errors? My experience is "out of the box" behavior is important, as Claude and other popular Hosts will default to it, and leaving these to be handled on a proprietary basis by MCP clients would mean the majority would not do it.
dsp-ant commentedon Nov 7, 2025
This was accepted by Core Maintainers
mcp: return input validation errors as tool results, not JSON-RPC err…
Return tool argument validation failures as tool execution errors