Error handling in tools with structured content

[Plasmadog]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

What is the recommended way of handling errors in a tool that uses structured content? If I return a CallToolResult directly, the generated output schema is effectively useless, but there doesn't seem to be any other way.

[mikekistler]

I believe you return a CallToolResult with isError set to true. See

https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling

[Plasmadog]

That doesn't really address the problem. As noted my question, if the return type of the method is CallToolResult, then I miss out on the output schema generation for the content that I really want to return. So how is it possible to handle errors correctly, while still having structured content and a generated schema?

[mikekistler]

Sorry ... should have provided more detail. Don't change the return type of your method. But you can generate a CallToolResult with isError = True by throwing an McpException, like this:

        if (count > 20)
        {
            throw new McpException("Count exceeds maximum limit of 20.");
        }