Testing MCP Tool Contracts Before They Break in Production

For every MCP tool, document the exact shape of its input and output: field names, types, which fields are always present versus optional, and what error responses look like. This sounds basic, but tools built directly on top of an internal API client often don't have this written down anywhere separate from the code itself, which makes a later change easy to make without realizing it's breaking.

A practical starting point is to draft the first version of the contract from real traffic. Record a sample of real tool responses and note, for every field, whether it was ever missing, null or a different type. Turn that observed shape into the written contract, then have the tool owner correct it where the observed behavior was accidental instead of intended. Starting from real responses catches the fields nobody remembered were optional, which are the ones most likely to break an agent later.

Write automated tests that check a tool's actual response against its documented contract, not just that a specific test call happens to succeed today. This catches the case where an underlying API adds a new required field, or changes a field from always-present to sometimes-null, before that change reaches an agent that assumed the old shape.

The team that owns a tool should test that it still honors its documented contract. The teams whose agents depend on that tool should have their own tests confirming the agent still behaves correctly against that contract. Relying on only one side misses cases: the tool owner doesn't know how the agent actually uses their tool, and the agent team can't see internal changes to the tool until they've already shipped.

A tool's documented contract shouldn't change without a version bump and a heads-up to every team whose agents depend on it, the same discipline you'd expect from any other shared internal API. Skipping this step is the single most common way a working agent quietly starts behaving worse, without a deploy of the agent's own code ever happening.

A short, simple notification, a message in a shared channel naming the tool and the change, is often enough. The goal isn't heavyweight process, it's making sure the change is visible to the people who'll be debugging its downstream effects three weeks later, when the connection to a routine schema update is much less obvious than it is on the day the change ships.

A contract testing routine looks like this:

1. Document each tool's input and output shape, including field names, types, which fields are always present, and what error responses look like.
2. Write automated tests that check actual responses against that contract, including format details such as timezone presence.
3. Have both the tool owner and each dependent agent team run their own tests against the contract.
4. Bump the version and notify every dependent team before a contract changes.
5. Run the tests in CI so a failing contract check blocks the merge.

Say a scheduling team adds contract tests to their MCP tool after a previous incident where a field's type changed unannounced. A few months later, an engineer refactors the tool's underlying API client for performance and, in the process, accidentally changes a timestamp field from always including a timezone offset to sometimes omitting it, depending on which code path handled the request.

The contract test, which specifically checks the shape of every field including format details like timezone presence, fails immediately in CI, before the change ever merges. Without it, this would have shipped cleanly, since neither the existing unit tests nor a quick manual check happened to exercise the code path that produced the malformed timestamp, and the agent consuming that field would have started making scheduling errors that were hard to trace back to a timestamp format regression. The engineer who made the change wasn't careless, the refactor was reasonable on its own terms; the contract test simply caught a consequence the refactor's author had no way to anticipate from inside their own change. That's the actual argument for contract tests: not that they catch careless mistakes, but that they catch reasonable changes with unreasonable side effects nobody could have been expected to predict on their own, which is exactly the kind of gap ordinary code review tends to miss.