AI agents that read the explanatory text in MCP tool responses as fact

Summary

The MCP server of a service developed at my own company splits long specialized documents into sections divided by headings and returns them. An MCP tool adds explanatory text to a response that tells the reader how to read the data. I call this text the response note. The development AI agent wrote response notes stating as fact that a section had certain contents, based on a classification made only from the words in the heading.

The two external AI products I asked to run a quality evaluation read the documents exactly as the assertions in the response notes and the usage text passed at connection time told them to. One product misread what a section contained, and the other stopped reading partway through. Both products acted as the text said, so the cause of these two misreadings lay in how the text was written, not in the readers’ ability.

The development AI agent took a sample of 50 documents, sorted the lines of the sections classified as the author’s judgment into kinds one by one, and counted them. Even in the 25 documents whose sections were classified from the words in the headings, 7.5% of the characters were quotations of claims made by people other than the author. The development AI agent rewrote the 27 places that contained assertions into text that conveys the nature of the data, the reason for it, and how to read it. After that, it decided not to put any behavior that reads the content of the body and decides on the reader’s behalf anywhere in the MCP server.

What you can take away

This article is for developers who write the response notes an MCP server returns, the descriptions attached to MCP tools, and the instructions passed at connection time.

• Three rules for writing response notes, and three examples of rewritten assertions.
• A table of the measured share of the author’s own text in the judgment sections of 50 documents.
• How, on the day after the response notes were rewritten, assertions found in the type labels, in the guidance values, and in another response note were fixed.
• The rule by which the development AI agent sorted the MCP server’s behavior into three kinds and decided not to include one of them.

This article is a design discussion about the MCP server of a service developed at my own company. It rests on five sources: commit messages, PR descriptions, design documents, test files, and the development memory, including its change history.