A compatible schema can still change an agent’s behavior

An order tool adds an optional field called include_archived. The JSON still validates for old callers. The release is described as backward compatible. Yet the assistant starts including archived orders in answers because the description and default behavior changed at the same time.

Compatibility has several layers in an agent system. A request can remain syntactically valid while its meaning, permissions or likely selection behavior changes. A release process needs to name those layers before choosing a version number and a rollout plan.

Keep four versions separate

The MCP protocol version describes the message contract negotiated by a client and server. The lifecycle specification defines initialization and version/capability negotiation. That is distinct from the version of your server package, the revision of an individual tool contract and the schema of your stored application data.

Record all four where relevant. A successful MCP initialization does not prove that an old client understands a new business field. A server package upgrade does not necessarily require a protocol-version change. A database migration can affect both even if the visible tool name remains the same.

Semantic Versioning provides a useful convention for declared public APIs: incompatible changes, compatible additions and compatible fixes have different version increments. First decide what your public API promises. A version label cannot answer a compatibility question the contract never defined.

Inventory the affected surfaces

For each tool change, examine the name, description, argument schema, default values, result schema, authorization requirements, side effects and error behavior. Include documentation and saved client configurations in the review.

These are review triggers, not a claim that every optional field is a breaking change. The consumer's contract and behavior determine the answer.

Work through an archived-order migration

Suppose version one of search_orders returns active orders only. The team wants authorized administrators to include archived records. Preserve the old default. Add a clearly named optional argument whose default remains false, and enforce archive access on the server even when the argument is true.

Do not silently reuse the same change to alter ordering, page size or date interpretation. Keeping the migration narrow makes a regression easier to identify. If a later release needs new defaults, treat that as a separate contract change with a visible migration path.

Test an old request against the new implementation and compare the selected record set, not just the response schema. Test a new request from a user without archive permission. Test an explicit false value, an omitted value and an invalid value separately; coercion can make those cases behave differently.

The human-facing description should state that archived records require explicit selection and appropriate permission. It should not suggest that a model can infer permission from the requester's tone or job title.

Expand, migrate, then remove

For changes that require stored data, introduce the new representation while the old application still works. Backfill or transform data through a controlled process. Make the application tolerate the transition state before making the new representation mandatory.

Validate the migration with counts and invariants appropriate to the data. If orders have stable identifiers, prove that the migration preserved those identifiers and their tenant ownership. A successful migration command is weaker evidence than a checked application invariant.

Remove old fields or aliases only after you have evidence that supported consumers no longer depend on them, or after an announced support boundary. Avoid leaving permanent compatibility code without an owner; it eventually becomes another undocumented interface.

Be precise about rollback. Rolling back application code may be safe while reversing a data transformation is not. Preserve the evidence and backups needed for the recovery path you actually intend to support.

A description edit is still a release input

Models use tool metadata to decide what to call. A description edit can therefore deserve a behavioral regression run even when no handler code changes. Keep the exact tool catalog used in an evaluation, including descriptions, rather than storing only a package version.

Run a representative task set against old and new catalogs. Include adjacent tools with similar purposes, ambiguous requests and tasks where the correct action is to ask a question. Look at unauthorized effects and incorrect record selection independently from fluent final answers.

Do not turn the result into a universal claim about compatibility. State which clients, fixtures and model configurations were tested. Keep a record of known unsupported combinations so operators do not have to rediscover them during an incident.

Roll out with a stop condition

A small canary group can expose integration issues before a broad release, but it only helps if someone is watching meaningful outcomes. Compare task completion, validation failures, permission denials and unresolved writes for the affected tool revision.

Define what stops the rollout in advance. For the archived-order change, an unauthorized archived record is a stop condition even if latency and overall success rates are normal. An increase in client validation errors may indicate result-schema assumptions you missed.

If the tool list changes during a session, follow the negotiated protocol's notification rules. In the referenced tools specification, a server advertises tools.listChanged and should send notifications/tools/list_changed when the available list changes. Still test clients that cache metadata or reconnect infrequently; emitting a notification is not evidence every consumer has refreshed its view.

Leave a migration note people can use

Write the release note around the caller's task: what changes, which requests remain equivalent, how to opt into the new behavior, and what to do if a client rejects it. Include the support period for old behavior and a contact or issue route that actually works.

A migration is complete when supported consumers can perform their intended work under the new contract and operators can explain the version running. Keeping schemas valid is part of that job. Preserving meaning and authority is the rest.