Versioning Tools Without Breaking Agents — Tool Use, Function Calling & MCP

A REST API's consumer is a compiled or generated client: a type checker or a build step catches a field rename or a newly-required parameter before the code ever runs, and the formal contract -- an OpenAPI spec, a protobuf file -- is checked once, at build time, not re-interpreted on every request. A tool's consumer is a model reading a free-text description fresh on every single call, with no compile step and no generated client standing between the words in the description and the decision the model makes from them. That difference is the entire subject of this lesson: the traditional definition of a breaking change -- did the wire shape change -- is necessary but not sufficient here, because a schema can stay byte-for-byte identical while the description changes what the model believes the tool does, and that is a behavior change every bit as real as deleting a field.

The tooling industry already has a vocabulary for this in semantic versioning -- additive changes bump a minor version, breaking changes bump a major one -- and that vocabulary transfers cleanly to schemas. It does not transfer cleanly to descriptions, because semver assumes a client checks compatibility once, at install time, and then trusts it until the next deliberate upgrade. A model re-reads a tool's description as an instruction on every call it makes, which means a wording change a human reviewer would wave through in a pull request as purely cosmetic -- rephrasing a sentence, tightening an example -- can silently shift which tool the model reaches for or which values it decides are valid, with nothing in a schema diff to flag it.

This lesson works through what that actually means in practice: a precise line between breaking and additive changes that goes beyond "did a required field appear or disappear"; why renaming a tool is categorically worse than any schema edit; four concrete evolution strategies, from additive-only changes through MCP's server-side capability negotiation; the often-overlooked cost that changing a tool's definition invalidates the cached prompt prefix for every session using it; a four-step deprecation discipline; the contract tests from lesson 24 applied specifically to pin a schema against silent drift; and what an MCP client actually does with `list_tools` when a server's catalogue changes mid-session.

Analogy🏏Cricket

🏏 Think of it like cricket: suppose Jasprit Bumrah's official player registration -- height, bowling arm, jersey number -- never changes season to season; that's the schema, the formal record that stays fixed. But the specific reconnaissance notes each opposition team's analyst circulates before a series -- "watch for the slower ball around over forty-five, he drops his front arm a fraction on it" -- those notes are what the batsman actually reads before facing him, not the registration card sitting in a filing cabinet at the board office. If the analyst quietly revises that scouting note between the first and second Test -- same bowler, same registration, differently described -- a batsman who trusts the old note gets undone by a ball he was never warned about, even though nothing about Bumrah himself changed on paper between the two matches. That is the exact shape of a tool description edit: the input_schema -- the equivalent of the registration card -- can be byte-for-byte identical, and if the words in the description change what the reader is told to expect, the reader's judgment changes exactly as much as if the parameters had changed, because the model, like the batsman, was never reading the registration card at all. It was reading the note.