MCP Tool Schema Changes: Review Before Execution

MCP tool schema change control should detect when a tool's name stays the same but its accepted arguments, description or operational meaning changes. Refreshing discovery is only the first step. Compare the new definition with the approved contract, assess affected permissions and tests, then decide whether existing clients and queued requests may use the changed tool.

This article is for gateway and integration teams operating MCP tools across release boundaries. It describes an application-level control pattern, not an additional MCP protocol requirement. The example is an internal draft-creation tool that gains a new recipient parameter. Even if that parameter is optional, its default behavior can change where information goes.

Separate discovery updates from deployment approval

MCP’s tools specification defines tool discovery, input schemas and list-change notifications. A notification tells a client to reconsider the available tool list; it does not establish that a changed business operation has been approved. Tool annotations also need an appropriate trust assessment rather than being accepted as authority merely because a server supplied them.

Use an approved registry entry containing the server identity, tool definition, connector version and responsible owner. Keep the discovered definition as an observed candidate until it passes the relevant checks. If discovery is unavailable, follow the deployment's documented freshness policy. Do not quietly expand tool behavior because the current metadata cannot be retrieved.

Compare semantics as well as JSON structure

Schema comparison can detect added properties, changed types and different required fields. It cannot determine every business consequence. A string field may retain the same schema while changing from an internal reference to an arbitrary URL. A description may begin encouraging a broader action without any schema modification.

Change	Why it matters	Evidence before acceptance
New optional destination	A default may route data outside the approved boundary	Explicit default, destination validation and negative cases
Wider enumeration	More operations or resources become selectable	Updated authority mapping and reviewed business scope
Removed required field	A formerly explicit constraint may become implicit	Defined omission behavior and tests for missing input
Description update	Model tool selection may change	Review of instructions plus representative selection tests
Output schema change	Consumers may misinterpret status or identifiers	Contract tests against downstream consumers
Same schema, new side effect	Structural compatibility conceals operational change	Connector release evidence and receiving-system observations

Treat compatibility in two dimensions. A client may still parse the request successfully while the action becomes unacceptable under the previous authority. Conversely, an added display field may require a client update without expanding permission. Record both conclusions instead of using one “compatible” checkbox for everything.

Pin the approved contract used for a request

Associate a request with the tool contract under which it was prepared and authorised. If the execution path observes a different contract, stop or re-evaluate according to an explicit policy. This avoids a time-of-check/time-of-use gap in which a request was approved against one meaning and executed against another.

The binding can use a stable version identifier and a digest of an agreed serialisation. Define which fields are included and how the digest is calculated. A digest alone does not prove the server will implement the definition. Receiving-system tests, restricted credentials and a controlled connector deployment remain necessary for the proposed pattern.

For queued requests, decide whether to drain under the old connector, cancel, or require renewed preparation and approval. Do not replace the contract reference in place. Preserve the old request and the reason a new request was created so the review history remains interpretable.

Test a harmless schema migration first

Create two synthetic versions of a draft tool. Version one accepts a case reference and body. Version two also accepts a destination, with no implicit external default. Prepare a request against version one, then switch discovery to version two before dispatch. The expected result is a visible contract mismatch or an explicitly approved migration, not silent acceptance.

Next, submit an unknown field, a destination outside the allowed set and a value that meets the JSON type but violates the business constraint. These tests distinguish schema validation from authorisation. Passing JSON Schema validation is not permission to act on a particular customer, system or record.

Finally, return a changed output that replaces a completed status with an accepted-but-pending status. Confirm that the caller does not treat provider acceptance as completion. This catches a different class of integration defect from an invalid input and belongs in the same migration review.

Recover from an unexpected change

If a contract changes unexpectedly, quarantine the affected tool rather than disabling unrelated workflows without analysis. Identify prepared, queued and already-dispatched requests separately. Refresh the definition from the trusted server, compare it with the approved record and determine whether the change is legitimate, accidental or untrusted.

Do not retry already-dispatched operations just because the client could not parse the result. Query the receiving system using a stable operation reference when supported. Preserve the raw result in an appropriately protected store and record the interpretation failure. A parsing error leaves the business outcome uncertain; it does not prove that nothing happened.

Make the review useful to the next release

The change record should identify affected clients, authority rules, evaluation cases and rollback limitations. Include the owner who can explain the operational meaning. If the only available evidence is a schema diff, mark the semantic review incomplete rather than assuming the missing information is harmless.

After acceptance, run a small controlled set of representative requests and examine the receiving-system state. Keep the previous contract available for interpretation of older evidence. Retaining it does not necessarily mean keeping the old tool executable; those are separate lifecycle decisions.

The worksheet is complete when it distinguishes observed metadata, approved contract and deployed behavior, and when a mismatched request has a tested outcome. This makes change control useful for a real deployment instead of turning discovery notifications into automatic permission changes.

Use the worksheet and related implementation guides

Use the parent guide for the wider architecture, then apply this article to one bounded implementation. The adjacent articles cover related decisions without replacing this worksheet.

Download the editable worksheet. Next step.

Engineering draft, 18 October 2026. Primary sources checked on this date; specialist review remains pending. The worksheets describe proposed tests, not measured customer results. OATI remains a developer preview. Local implementation evidence does not establish independent assurance, customer acceptance or production readiness for a particular deployment.