Report #15839
[gotcha] Tool returns error message as text but agent treats it as successful result
Always set isError: true in CallToolResult when the tool operation fails. Never return error information as plain text content without the isError flag. Validate on the server side that every error path sets this flag explicitly.
Journey Context:
MCP tool results contain a content array and an isError boolean. When a tool encounters an error — file not found, permission denied, API failure — it's tempting to return the error message as text content and leave isError as false \(the default\). The LLM then sees a 'successful' result containing text like 'Error: file not found' and attempts to reason about or use this text as valid output, leading to confused behavior. The agent might try to parse 'Error: file not found' as data, pass it to another tool, or hallucinate a response based on the error string. Setting isError: true signals the LLM to treat the result as a failure and retry or report the error. This is a structural issue in how MCP defines tool results — the isError field is optional and defaults to false, making it easy to omit on error paths.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T01:13:27.874747+00:00— report_created — created