Tool schemas should be pinned like dependencies, not rediscovered on reconnect

An agent runtime should pin tool schemas the way an application pins dependencies. Rediscovering a server’s current tools on every reconnect looks flexible, but it silently lets executable authority change underneath a tested agent. A renamed parameter, softened description, wider enum, or newly advertised tool can alter the model’s choices without a code release. That is dependency drift with a probabilistic caller.

The danger is larger than ordinary API incompatibility. Tool names and descriptions enter the model’s decision context, so metadata is both interface and instruction. Cross-server tool shadowing can make an untrusted server’s plausible tool compete with a trusted one. Description tampering can redirect intent while preserving a syntactically valid schema. A widened argument may expose a new destination or method that the policy layer never reviewed. The call still validates, yet the effective capability has changed.

I want installation to produce a signed or locally trusted manifest containing server identity, namespace, tool names, normalized schemas, annotations, and a cryptographic digest. Reconnection should compare discovery against that manifest before any changed tool reaches the model. An exact match can proceed. An additive change stays unavailable until reviewed. A breaking or suspicious semantic change fails closed, records the diff, and identifies which agents and policies depend on the old contract. MCP servers are supply-chain dependencies; reconnect is not permission to upgrade them.

Normalization matters because harmless serialization differences should not trigger incidents. The digest should ignore key ordering and formatting while preserving descriptions, required fields, enum values, defaults, annotations, and namespace identity. But the human review cannot stop at structural diffing. “Send a message” becoming “send or forward any message available to the account” may be schema-compatible and authority-expanding. The review needs semantic risk classes: cosmetic, compatible, capability-widening, destructive, and identity-changing.

Pinning also creates a release boundary. Agent behaviour depends on the model, prompt, policy, tool inventory, schemas, and state readers together. A production agent release must version the whole system, so the tool-manifest digest belongs in every run record and deployment artifact. Replay can then reconstruct the interface the agent actually saw. Rollback can restore a known contract instead of merely restoring application code while the remote tool surface keeps moving.

This is not an argument for freezing integrations forever. It is an argument for making change deliberate. Schema evolution is producer-consumer negotiation: providers publish versions and compatibility intent; consumers test candidate manifests, update policy, and promote them through staged environments. A registry should preserve version history and revocation state, not just the newest description returned by the server.

The operational payoff appears during incidents. A run ledger that records only a server URL cannot prove which tool definition influenced a compromised action. A recorded manifest digest can. Investigators can identify the first changed reconnect, enumerate affected runs, revoke the suspect version, and replay against the prior contract. Pinning converts a vague third-party dependency into a queryable blast radius.

There is one precise concession: exploratory, read-only sessions inside a disposable sandbox can reasonably accept live discovery when every tool is namespaced, results are treated as untrusted, and no private data or persistent effect is reachable. That is a development posture, not a production default. The moment credentials, write scopes, durable memory, or cross-tenant data enter the session, unreviewed discovery becomes an authority change.

Tool schemas are security boundaries, but a boundary has value only if operators know when it moved. Pinning supplies that knowledge. Verification turns reconnect from an implicit upgrade into an explicit comparison, and promotion turns comparison into governed change. Flexibility remains available; surprise does not.