Change on the Agent Surface

Governing change to the MCP tools an agent binds to, where versioning does not reach

Everything I have written about managing API change assumes a consumer who reads. A developer integrates against a contract, and when the contract moves they read the changelog, they see the deprecation notice, they follow the migration guide, and they update their code before the sunset date. The entire apparatus — semantic versioning, the changelog, the roadmap, the Sunset header, the twelve-month runway — is a communication system built for a person. When the consumer is an agent, most of that apparatus keeps working and one part of it quietly stops, and the part that stops is the part almost nobody is looking at. I want to be precise about which part, because the sloppy version of this argument is that agents change everything, and they do not.

Start with what is actually there, because MCP is not an ungoverned space and it is not fair to describe it as one. The Model Context Protocol has a feature lifecycle and deprecation policy that is genuinely good — better than what most API providers give their own paying customers. A feature moves through Active, Deprecated, and Removed. There is a minimum twelve-month window between deprecation and the earliest possible removal. The deprecation proposal must document the migration path, or state explicitly that none is required, and if it names a replacement that replacement has to already exist. There is a single canonical registry page listing everything on its way out and by when, so an implementer does not have to reconstruct that picture from changelogs. The client libraries are obliged to mark the deprecated surface using the language’s native mechanism and should emit a runtime warning when someone exercises it, and a library that consistently fails to do that can be relegated. That is the deprecation practice I have been asking API providers for since 2015, and the working group wrote it for itself and shipped it. Anyone telling you this ecosystem does not take change seriously has not read the policy.

Then look one layer down, at the registry where servers are published, and the character of the thing changes. A published server must define a version string, that string must be unique for each publication, and once published it cannot be altered. Semantic versioning is recommended. Version ranges are prohibited. If a version string fails to parse as semver it is always marked latest. All of that is real governance and it is all governance of identity — it exists so that a registry can tell you which publication is which and which one is newest. There is a deprecation status in the registry metadata, so a publisher can flag a listing as deprecated and leave a free-text message. What there is nowhere to put is a date by which the thing will stop working, a structured pointer to what replaced it, or any statement scoped smaller than the entire server. You deprecate a listing. You cannot deprecate a tool.

And then there is the layer below that, which is the tool surface itself — what tools the server exposes, what they are named, what their descriptions say, what their parameters are called — and nothing governs it at all. That is the layer an agent actually binds to. A model does not consume your server version. It consumes a list of tools with names and descriptions, and it decides what to call and how to call it on the basis of that text. The discipline in this ecosystem degrades in exact proportion to how close you get to the thing the consumer depends on, and that is the finding, not any claim that people are being careless.

The measurements bear out that nobody is being careless. When I walked the entire public MCP registry I found 66,954 publication records across 20,359 distinct servers, and 96.9% of the version strings parse as valid semantic versions. That is near-total compliance with a recommendation that carries no enforcement whatsoever. This is not a population that ignores versioning guidance; it is a population that follows versioning guidance closely and has only been given guidance about identity. At the same time, 59.5% of registered servers published exactly once and never again, only about one and a half percent ever use the deprecation status that exists, and across 369 first-party MCP server repositories exactly one mentions a sunset in its README. People are doing what they were told. The gap is in what they were told.

The specific thing that breaks, and the reason the traditional taxonomy does not transfer cleanly, is that a tool description is not documentation, it is input. When you write a description for an MCP tool you are writing part of the prompt that decides whether a model calls that tool, and with what. Rewrite it and you have changed the behavior of every agent bound to it. And that change produces no schema diff, trips no semantic version rule, fails no Spectral lint, and passes every breaking-change gate anyone has built, because all of those instruments were designed to watch structure and the change was in prose. Of the 61,097 MCP tools I have catalogued, 58,937 carry a prose description — the ungoverned surface is not a corner case, it is nearly the whole thing. Engineers running this in production report exactly what the mechanism predicts: MCP tools break silently, a renamed parameter or an edited description sends the model somewhere else, and there is no error to catch. That is a breaking change regardless of whether the JSON schema is backward compatible, and the classification we inherited has no name for it.

So the honest conclusion is not that breaking-change classification no longer applies to agent-facing APIs. It is that our classification is incomplete rather than obsolete, and the correction runs toward more surface to govern, not less. It is tempting to argue the other way — that because there is reasoning on the other end, an agent absorbs change the way a person absorbs a redesigned interface, so we can evolve faster and worry less. There is something real in that: an agent genuinely will cope with a field renamed from qty to quantity in a way that would break every hand-written client. But the inference does not survive contact with the rest of the surface. The tolerance runs in one direction only. Agents are more forgiving of syntactic change and less forgiving of semantic and economic change than the humans they replaced, because a human who hits a 402 or a revoked scope or a new rate limit files a ticket, and an agent retries, degrades, or silently stops producing the outcome somebody is depending on. The things I have argued for years are the real breaking changes — a price change, a rate limit, a terms change, a scope you can no longer get — get worse under agents, not better, because the party that would have noticed is not a party anymore.

There is also a cost question hiding inside the argument for evolving faster, and it is the same question I have been asking since 2016, when Darrel Miller pushed me to think about change-resilient client code and I could not decide whose job it was. Saying the agent can deal with it does not make the change free. It moves the cost from the producer, who could have written one deprecation notice, to every consumer, who now pays in tokens, latency, retries, and wrong answers, at a volume nobody is measuring. We have run this play before. We offloaded the hard design work onto mobile developers with GraphQL and called it flexibility. The agentic version of the same move is to skip the extension design and let the model sort it out, and it will look like velocity right up until the first time somebody’s agent quietly stops booking the appointments.

The most telling thing I have seen is where the market has actually put its fix. Cloudflare shipped a feature letting portal administrators rename and redescribe the tools of servers they do not own, and the stated reason is that you have no control over how the server author named the tools or wrote the descriptions, and unclear names make it harder for agents. Read that twice. Nobody builds an override layer for metadata that does not matter, so it is independent confirmation that the prose is load-bearing. But look at which side of the table the fix is on: the answer shipping in production is the consumer overriding what the producer wrote, not the producer telling the consumer anything. That is consumer-side governance arriving on its own, in the absence of a producer-side layer, and it is what always happens when producers do not give consumers what they need — the consumers build it themselves, badly, one at a time, and the ecosystem ends up with thousands of private forks of your metadata and no shared truth about what your tools do.

So here is what I would ask of anyone operating an MCP server today. Treat the tool description as part of the contract, and give a description change the same notice you would give a schema change, because behaviorally it is one. Version the tool surface rather than inheriting a number from somewhere else — the common advice to align your server version to your underlying API version is convenient and it makes the most agent-relevant class of change invisible by construction, since your tool descriptions can be rewritten without your API moving at all. Understand that removing a tool is the most severe thing you can do, more severe than it was in a world of human integrators, because a developer who loses an endpoint reads your changelog and adapts and an agent bound to a tool that is no longer listed simply stops being able to do the thing. Say what is going away and say when, in a place a machine can read, because a status flag that records what already happened is not planning information. Test behaviorally rather than structurally, since a schema diff provably cannot see this class of change and only running the agent against the new definitions will tell you whether it still does the right thing. And carry your business changes into the same discipline as your technical ones — the price, the rate limit, the scope — because those are the changes agents handle worst and the ones we have always been sloppiest about announcing.

None of that requires a new specification to get started, and some of it will eventually want one. The registry already crossed the line from identity into lifecycle the moment it added a deprecation status; giving that status a sunset date, a structured successor, and tool-level granularity is an incremental proposal into a working group that has already demonstrated it will adopt a serious deprecation policy when someone writes one. That is the difference between saying something is broken and doing the work. This is not broken. It is unfinished at exactly one layer, and it happens to be the layer everything else now depends on.

Discovery

Learnings

Guidance

Toolbox

Alignment

API Evangelist LLC

Change on the Agent Surface

References

Guidance Details

Explore more

Discover APIs