MCP Tool Versioning: Pinning What an AI Agent Is Allowed to Do

Everything else your company runs has a release number. The database has one. The laptop image has one. The payroll system nobody may touch in the last week of a quarter has one, and the person who approved it can tell you which. Then an AI agent arrives with a list of tools, and the tools have names. Names are all they have. Nothing on the list says which update_record the agent will call tomorrow, and nothing has to tell you when the answer changes.

MCP tool versioning is the fourth of the six AI operator security controls, and the one that keeps the first three true after the day you verified them. The control is that a tool’s definition is pinned: it carries a version, it changes only with notice, and you can hold the version you approved until you have read the next one. This guide walks a buyer through that sentence, from what a tool definition is to what to put in the RFP. It expands Control 4 of the AI agent security checklist, the index for the series.

The series rests on one idea. AI operator security is being safe from the AI agents you operate. Most AI security protects you from someone else’s model. AI operator security protects you from your own agents. The term and the reasoning behind it are in AI operator security; the AI agent security checklist turns them into six questions, and this guide takes one of the six slowly.

What the Agent Actually Reads

A tool, in the vocabulary this series uses, is one operation an MCP server exposes: search_customers, update_ticket, issue_refund. What matters here is what a tool is made of, because that is what your security review approved.

The MCP specification (current revision, 2026-07-28) says a tool definition includes seven things: a name, the unique identifier; an optional title for display; a description, the human-readable description of functionality; optional icons for display in user interfaces; an inputSchema, the JSON Schema defining expected parameters; an optional outputSchema for structured results; and optional annotations, properties describing tool behavior. That is the whole definition, and the entry a buyer would want most is missing: a version.

Who reads which field is the point. The model, which decides whether to call the tool at all, works from the name, the description, and the input schema: the description tells it when the tool fits, the schema what to send. It never sees the vendor’s code, and it never sees last month’s description either. It sees whatever text arrived this session.

Two consequences follow. The description is a prompt the vendor writes and your agent reads. The schema is the capability: a tool whose schema gains one optional field has gained a capability, however the name reads. Your review approved both on a particular day. This control answers whether that is still what the agent is reading.

How a Definition Changes Under You

A tool definition is not a file you downloaded. It is a reply. Each session the client asks the server for its tools with tools/list, and the server answers with whatever it has that day. A server can also change the answer mid-session. It can declare a listChanged capability, which the specification says indicates whether the server will emit notifications when the list of available tools changes, and when the list does change, a server that declared the capability should send a notification named notifications/tools/list_changed to clients that have asked to hear about it. The client then asks for the list again and hands the new definitions to the model.

Read that as a buyer. The notification goes to the client process, not to a person. It carries no detail: the specification’s example is a method name with no parameters. It is a should rather than a must. And a definition that changes overnight needs no notification at all, because the next session opens with a fresh tools/list. A notification to the client is not notice to the buyer. It is a cache invalidation, and the people who approved the old list are not on the distribution.

The failure pattern that follows is quiet. The update tool that also deletes: update_record gains an optional parameter that clears a record when the new value is empty, and the agent uses it the first time an empty value looks right. The search tool that also exports: search_tickets gains a flag to return every match as a file, and a read-only tool is now the export the allow-list was built to prevent. And the one buyers rarely check: the description rewritten so the model uses the tool more often. A description is a prompt, and a vendor whose metrics reward usage will tune it, in good faith, until the agent reaches for the tool in situations your review never considered. Nobody attacked anything. The name stayed. The tool moved.

The hostile version has a name. In April 2025, Invariant Labs described tool poisoning: malicious instructions embedded within MCP tool descriptions that are invisible to users but visible to AI models, and a variant they called a rug pull, in which a server changes a tool description after the client has already approved it. The mechanism is the one a well-meaning vendor uses to ship a feature.

Annotations do not close the gap. A server can label a tool read-only or destructive, and a careful client uses the label to decide when to ask first. But the specification says clients must consider tool annotations untrusted unless they come from trusted servers, and even a trusted server’s label is a statement about itself at a point in time, checked against nothing. An annotation is a hint. A version is a commitment that the definition has not moved. The control needs the second.

What MCP Tool Versioning Means in Practice

The fix is ordinary engineering. From the buyer’s chair it has six parts, each a thing you can be shown.

A version identifier on every tool definition. The protocol does not supply one: a server identifies itself with a name and a version of its own, but a server that moved from 2.3 to 2.4 has told you that something among forty tools changed, not which. The identifier has to sit on the tool, in its metadata, its name, or its description, and it has to change whenever the description, the schema, or the behavior behind them changes. Unchanged text over code that now deletes is a changed tool, and an honest version says so.

Then a changelog, per tool and dated; notice to a named contact on your side before the change ships, not a release note the morning after; a review window long enough to read the diff and rerun the injection test from control 5; a pin that holds your agent’s identity on the approved version while the window is open; and a diff on request, the old definition beside the new.

The pin is the part vendors push back on, so be precise about what it costs them: serving two versions of a definition to two identities for the length of a window. A server that scopes tools/list to the caller’s identity, the design in MCP auth and security, can do this; so can a gateway in front of the server that holds the approved definitions and masks the rest. A vendor who says the pin is impossible is usually saying the tool list is not per identity either, which is a finding on control 1.

An Allow-List That Can Grow Is Not an Allow-List

The first control in this series is a short list of tools attached to an identity and enforced on the server. The list is made of names, and it can grow two ways without anyone adding a line to it. The server can add a tool, which the list-changed notification announces to the client and to no one else. Or a tool already on the list can widen, the same name around a larger capability, which nothing announces at all. The permissions guide named scope sprawl as a failure mode: three tools at launch, forty a year later. This is how the sprawl arrives, one quiet definition at a time. An allow-list the vendor can lengthen without telling you is not an allow-list. It is a snapshot of one.

The other controls lean on the version the same way. The agent’s own identity is where the pin attaches. The approval gate is per call on a tool name, and an approver who reads update ticket and clicks approve has approved whatever that name does today, so a changed definition goes back through the gate. The injection test was run against a description and needs running again when the description changes. And the audit log should carry the version on every call, because that log line is the only literal answer to the question in the RFP.

How to Verify the Control

The vendor says the tools are versioned. Three steps turn the sentence into evidence, and the first two need no vendor in the room.

First, pull the current definitions. Call tools/list as the agent’s own identity, or have the vendor do it on a screen you can see, and keep the full reply: every tool’s name, description, input schema, and annotations. Second, compare the reply to the copy you kept. The permissions verification told you to date and keep the tools/list output; that file is the approved definition, and the comparison is a diff. Third, ask the vendor for the diff since approval. A vendor with the control produces it from the changelog the same day. One without it reconstructs it from a code repository, or cannot, which is also an answer.

Then ask what happens when the vendor ships a version your side has not reviewed. The right answer is that your agent stays on the old one until the window closes.

What to keep: the approved definitions, dated; the vendor’s changelog since; and the diff you ran, which should be empty or match the notices you received. That is the artifact: not the vendor’s assurance that nothing changed, but your copy, and a comparison against it that comes up clean.

Failure Modes

All seven fail the same question. Ask which version the agent called this morning, and the answer is a shrug.

The Contract Term and the RFP Question

The reason every control needs a term in the contract is set out in the checklist. The term from the hub is short: tool changes come with notice and a version you can pin, with a window to review before the new version runs against your data. Four details make it enforceable. A change means a change to the description, the schema, or the behavior behind them. Notice goes to a named contact before the version is served to your identity. The window is a number of days, and the pin holds for all of them. And the diff is deliverable on request, for any two versions. A sunset is fair in return: the vendor may retire the old version when the window closes, so the buyer gets a review, not a veto.

Pair it with the permissions term, that enforcement is server-side and the contract names the point, because the two describe one thing: a list the vendor cannot lengthen, holding definitions the vendor cannot move, without your knowing. Both belong with the security terms in SaaS vendor security due diligence.

Conclusion

Versioning was never exotic. Everything else your company runs has a release number, and the people who approve changes to those things would not accept the current one as an answer. The tools an agent calls are the last place that answer still passes, because the agent will never complain about a change it was not told about. It will use it.

The name stays. The tool moves. Pin the definition you approved, and make the vendor tell you before it moves again.

Related Guides

• AI Agent Security Checklist – The six AI operator security controls, with the artifact to request for each
• AI Agent Permissions – Control 1: the allow-list this control keeps true
• Prompt Injection Defense for AI Agents – Control 5: the test to rerun whenever a description changes
• AI Agent Audit Log Requirements – Control 6: the log line that carries the version on every call
• MCP Terminology – Servers, tools, and the vocabulary this guide assumes
• MCP Auth and Security – Per-identity scope design, which is where a pin attaches