𝗧𝗵𝗲 𝗠𝗖𝗣 𝗧𝗼𝗼𝗹 𝗖𝗵𝗮𝗻𝗴𝗲𝗱 𝗜𝘁𝘀 𝗦𝗰𝗵𝗲𝗺𝗮. 𝗬𝗼𝘂𝗿 𝗔𝗴𝗲𝗻𝘁 𝗗𝗶𝗱𝗻'𝘁 𝗡𝗼𝘁𝗶𝗰𝗲.
Your tool call did not crash. It returned a 200 status code and valid JSON.
But it ran against the wrong contract. The upstream server renamed one field three days ago. Your agent kept sending the old name. The server quietly dropped it. The result came back empty. No error appeared. Nobody noticed for a week.
This is the silent failure. It is not the loud kind where logs turn red. It is the kind where the server smiles back, but the data is wrong.
MCP servers can change a tool contract between calls. They can rename a parameter or change a field description. These changes often remain structurally valid. JSON validation passes. The server answers 200. Your agent acts on wrong data without a single error.
The fix is simple: • Pin a SHA-256 hash of each tool contract. • Include both the schema and the description in that hash. • Check the hash before every call. • Stop the call if the contract drifts.
We focus on whether a tool answers. We check status codes. We set timeouts. We retry on 5xx errors. Almost nobody checks if the contract changed between the moment the agent learned the schema and the moment it made the call.
An MCP server exposes tools through tools/list. Each tool has an inputSchema and a description. Your agent reads this once at the start of a session.
If the server updates, it can:
- Rename a parameter (like query to q) while leaving extra properties open. The old parameter is silently dropped.
- Change a field's meaning. A limit might change from "max results" to "page index." The type stays an integer, so validation passes.
- Narrow an enum. A valid value might get coerced into a new default.
The MCP spec says a server SHOULD notify a client if a list changes. It does not say it MUST. Many servers will not send this notification. Even if they do, they might not tell you that a specific tool schema changed.
Stop relying on structural validation. It cannot see a change in meaning.
Treat your MCP tools like software dependencies. Use a lockfile approach. On the first contact, take a SHA-256 hash of the tool's schema and description. Before every call, recompute the hash. If they match, proceed. If they do not match, flag the drift and stop.
Hashing the description is the secret. If a parameter changes from "max results" to "page index," the schema looks the same. The hash changes because the words changed. This catches the semantic drift that validation misses.
Do not guess when a contract drifts. Do not retry blindly. Pause, log the difference, and fix the contract.
Source: https://dev.to/0012303/the-mcp-tool-your-agent-calls-changed-its-schema-it-didnt-notice-5g6m
Optional learning community: https://t.me/GyaanSetuAi