MCP tools report failure in two ways. Protocol errors mean the request itself was wrong, such as an unknown tool or a malformed call. Tool execution errors mean the tool ran but failed, and they carry a message the model can use to fix its next attempt. Design your errors with that split in mind.
The two mechanisms
The tools page of the specification describes them.
Protocol errors cover issues with the request structure that models are less likely to be able to fix: an unknown tool, a request that fails the schema, or a server error. They come back as standard JSON-RPC errors with a code and message.
Tool execution errors hold actionable feedback the model can use to self-correct. The spec lists API failures, input validation errors such as a date in the wrong format or a value out of range, and business logic errors. They appear inside a normal result with an error flag set to true.
{
"result": {
"content": [
{ "type": "text", "text": "Invalid departure date: must be in the future." }
],
"isError": true
}
}
What clients should do
The spec says clients may pass protocol errors to the model, though recovery is less likely, and should pass tool execution errors to the model so it can adjust and retry.
Designing good execution errors
- Say what was wrong and what is valid. "Date must be in the future, current date is shown" beats "bad request".
- Keep it short and plain. The text goes into the model's context.
- Do not leak internals. Stack traces, file paths and tokens do not belong in the message. The spec requires servers to validate inputs, control access, rate limit and sanitise outputs.
- Be consistent. Use the same wording for the same failure, so retries converge.
Why this matters for agents
An agent that gets a vague failure may loop, burning time and tokens. An agent that gets a clear execution error often fixes the argument and succeeds. The spec also tells clients to implement timeouts for tool calls and log tool usage for audit.
There is a security angle. Error text is untrusted content flowing back into the model. A hostile server can put instructions in an error message just as it can in a description. Clients and users should treat results with suspicion, as OpenAI's docs and Anthropic's connector guidance both warn about prompt injection in tool outputs.
Stateful tools and expiry
The spec's guidance on stateful tools says a call against an expired or unknown handle should return a tool execution error that says so, so the model can create a new one.
For related security reading, see MCP server prompt injection vectors.
Quick check
Which error type should an invalid date use?
A tool execution error, because the model can read the message and retry with a valid date.
How do I mark a tool execution error?
Return a normal result with the error flag set to true and a clear text message.
Sources
Last reviewed: 19 October 2026.
