An agent prepares a customer update, waits for review, and resumes after a connector deployment. The tool name is unchanged, but its status argument now means the customer's overall lifecycle instead of the support ticket's state. The JSON still parses, which hides the change.

A public MCP proposal on schema fingerprints asks how clients should detect contract changes and distinguishes several kinds worth examining. Your migration needs an explicit compatibility rule for your own clients' contracts.

Define the contract beyond JSON shape#

Record the tool's identity, input and output schemas, argument meanings, side effects, and target system. A description-only change can alter model behavior while validation passes unchanged.

Separate syntactic from semantic compatibility. An optional field is syntactically compatible, yet a new default that changes who receives a notification alters the action.

MCP's tools specification defines input and optional output schemas. Validate against them and keep your own version policy for business meaning.

Work through a pending update#

Suppose version one accepts ticket_id and status: "resolved", and version two accepts record_id, record_type, and state. A pending plan holds a reviewed request to resolve ticket T-41, and an adapter can translate it only if it preserves that exact object and action.

The translation produces record_type: "ticket", retains T-41, and maps the old state by a documented rule. It does not infer a customer record from the ticket's account or choose a vaguely similar state, and if the target system changed what resolution means, the old request needs a new review.

Before execution, compare the translated action with what the user authorized, since a new tool version is not new user intent. The approval design guide explains why the target and concrete change should be visible at that point.

Change	Treatment	What to verify
Documentation correction	Refresh definitions	Selection behavior remains sensible
Optional nonconsequential field	Accept old inputs	Default preserves prior meaning
Required field added	Explicit adapter or replan	Missing value is not guessed
Target or side effect changed	New action review	Authority covers the revised operation
Output field removed	Update consumers together	Completion checks still work

Treat this table as a starting policy.

Test stored plans, not only fresh requests#

Fresh requests exercise the newest prompt and schema together. The harder case is yesterday's plan consuming today's tool result; keep fixtures for it.

Test a pending read, a pending write, an interrupted multi-step task, and a result another agent consumes. Include invalid old arguments so the adapter proves it rejects unsupported cases: a migration that quietly drops unknown fields turns a targeted action into a broad one when a filter disappears.

Also test output changes: an agent can complete a write correctly and still miss completion because the returned identifier moved. Preserve the object reference and terminal result in the new response, or update the consumer's completion logic in the same migration.

Give old conversations a controlled recovery path#

If compatibility cannot be established, return a contract-change error with the operation identity and a safe next step. Refresh discovery, reconstruct the intended action from the request and preserved state, and review any changed effect before continuing.

Do not tell the model to "adapt as needed" with a credential that performs both old and new operations; that moves a migration decision into an unreviewed execution step. A failed read can usually be replanned automatically; a changed write needs specific review.

Keep the previous adapter for a documented transition period if it preserves the provider's semantics, then retire it. Avoid indefinite aliases whose meaning drifts.

Review the migration at the next action boundary, while the target and effect can still be compared with the user's intent. Deixic's action lifecycle and MCP gateway documentation cover routed requests and results. Keep contract comparisons, migration adapters, and saved-plan fixtures together so a maintainer can review the next change against known behavior, including a test of what happens to yesterday's unfinished task after tomorrow's deployment.