The new connector passes its health check and returns a customer record. The old connector returned the billing account and the new one returns the parent company, but both display the same customer name. The agent's brief still reads naturally, and its next update targets the wrong object.

A connector migration changes meaning even when the tool names stay familiar. The MCP discussion about tool contract drift raises the related problem of detecting changed interfaces. Compare business meaning as well as schemas.

Write down what the old connection guaranteed#

Choose a representative task and trace what it depends on: object identity, scope, permissions, field meanings, pagination, freshness, and error behavior. Include undocumented assumptions in consumers, such as "the first result is always the primary account."

Do not preserve a wrong assumption for compatibility. Repair it, add a test that states the intended behavior, and keep that correction separate from accidental changes the replacement introduces.

Compare reads without duplicating writes#

Run a controlled read comparison with the same permitted identity and target. Normalize formatting differences, then compare stable identifiers, essential fields, omitted values, and completeness indicators. List the differences that affect the user's decision.

Never send live writes through both connectors to compare them, because that creates duplicate notifications or conflicting updates. Use a provider test environment, a reversible fixture object with explicit authorization, or a recording adapter that validates the proposed request without executing it.

Microsoft Graph's query parameter documentation shows how selection and filtering affect returned data. A replacement that changes either can look more efficient while omitting fields or records the original task needed.

Contract area	Comparison question
Identity	Does the same identifier refer to the same object?
Access	Does the same principal see the intended set?
Completeness	Are later pages and omitted fields visible?
Freshness	Does the result describe observation time accurately?
Writes	Does the proposed change have the same side effects?
Recovery	Can an interrupted old task continue safely?

Migrate the account brief#

Take an agent that reads a billing account, reviews unresolved support commitments, and prepares an internal note. The old connector returns an empty string for an unknown renewal date and the replacement omits the field. A consumer that treats omission as "no renewal" produces a misleading conclusion.

Define a normalized representation with explicit unknown, absent, and known values where the distinction matters, and keep the source identifier and link for each field. Then test an account with no renewal date, a closed account, and two accounts sharing a company name.

Next compare support commitments. If the new connector returns only open tickets while the old one included unresolved promises in recently closed tickets, the simplification changes the job. Extend the query or change the brief's declared scope with the business owner's agreement.

Plan the cutover for unfinished work#

A task can discover an object through the old connector and resume through the new one. Keep enough identity information to translate the object safely: if the identifier namespace differs, maintain an explicit mapping or re-resolve the target from authoritative fields.

A provider job already submitted through the old connection stays tracked by its original job identifier. Switching connectors does not make it disappear, so keep the status path available until those jobs reach a terminal result.

Returning traffic to the old connector in a rollback does not undo writes the new one made. Record which connector version executed each action so recovery uses the right semantics and credentials.

Accept the replacement by finished jobs#

Accept the migration on a completed user job: the right object, the right evidence, the intended proposed change, and the expected final artifact.

Include a denied read, a deleted object, a later page, a timeout, and a missing optional field in the comparison suite. Check the agent's final answer for overstatement, especially when one connector returns partial data more quietly.

For the routed path, see Deixic's connection setup and action evidence. Keep the old-to-new contract comparison with the connector's operating instructions, so the next migration starts from it instead of rediscovering what "customer" meant.