Tool contracts need version numbers and deprecation windows, just like APIs

Why an agent tool is a public interface the moment more than one runtime depends on it — and what that requires architecturally.

The first agent that calls a tool treats it like a function. The second agent that calls the same tool turns it into an API, whether anyone planned for that or not.

A tool used once is a shortcut; a tool used twice is a contract

Early agent integrations tend to start as a direct call from one assistant into one enterprise system: an API key, a request shape, a response the model learns to parse. That works exactly until a second agent runtime needs the same capability, or the target system changes its schema, or a security review asks who is allowed to call it and with what identity. At that point, the informal shortcut is already load-bearing for more than one caller, and nobody designed it to be.

The gateway exists to make that transition deliberate instead of accidental — to treat every integration as a versioned contract from the first day, so a second caller is a registry lookup, not a new point integration.

System design: a registry between agents and enterprise systems

Every tool an agent can call is published to a central registry with a stable name, an owner, a version, and lifecycle rules, rather than being wired directly into whichever agent needed it first.

• Connector adapter normalizes authentication, schema, errors, retries, and rate limits for one enterprise system, so that quirk lives in one place instead of in every agent that touches SAP or Salesforce.
• Versioned tool contract gives the capability a name and a version independent of the system behind it — the tool can evolve without every caller needing to know the underlying API changed.
• MCP registry is the single place a new agent runtime looks to discover what it is allowed to call, with ownership metadata attached so a question about a tool has an answer.

What "versioned like an API" actually requires

Treating a tool as a contract is not just giving it a name. It means the same lifecycle discipline a public API would need, applied to something that was previously invisible outside the team that built it.

• A schema change ships as a new version, not a silent mutation of the existing one
• Existing agent runtimes are not broken by a change they didn't ask for
• A deprecation window gives every known caller time to migrate before the old contract disappears
• Retirement is a scheduled event, not a surprise the next time an agent calls the tool

This is the direct cost of the registry-over-point-integrations decision: it adds platform governance that a single hardcoded integration never needed. What it removes is duplicated authentication, duplicated error handling, and — the part that only shows up later — every agent runtime having to individually discover that a tool changed underneath it.

Identity has to survive the trip through the registry

A registry that centralizes tool access without centralizing identity would just create one well-organized place for a privilege-escalation bug. The gateway propagates the calling user's own delegated context through every layer, instead of every tool executing under one shared service identity that can act for anyone.

• The agent discovers only the tools permitted for the current user, tenant, and task — not the full catalog
• Inputs are validated against the tool's schema before the adapter ever reaches the enterprise system
• A high-impact write can require an approval step the model cannot skip
• Every call is recorded with identity, latency, cost, and policy outcome on one trace, correlated back to the task that triggered it

Token propagation is harder to build than a shared service credential. It is also the difference between an audit log that can answer "who did this" and one that can only answer "the platform did this."

From production: why the boundary stays deterministic even after the registry exists

The registry solves discovery and versioning, but it does not, by itself, stop a model from proposing something it shouldn't be allowed to do. That boundary is enforced one layer further in: the model may propose an action — "update the lead stage," "create a case" — but code validates the schema, checks authorization and scope, executes the call, and records the outcome. The agent never gets a code path that skips validation because the request came from a model instead of a human.

That separation is what let two independent integration teams debug a real production disagreement without re-litigating the original design choice. SAP's session model and Salesforce's connected-app scopes turned out to disagree about what "the same user" meant, and the eight-week integration effort that followed was possible to reason about precisely because the identity-propagation decision, and the trade-off it accepted, had already been written down — not because the registry made the disagreement go away on its own. The registry made the tools discoverable and versioned; the deterministic boundary and the recorded decision made a hard interoperability bug debuggable instead of mysterious.

What to carry forward

• Treat the second caller of any tool as proof it is already a contract, not a shortcut
• Version tool schemas and give existing callers a deprecation window before retiring one
• Propagate the calling user's identity through every layer instead of a shared service credential
• Keep validation, authorization, and execution in code the model cannot bypass
• Record identity, latency, cost, and policy outcome on one trace per task, not per call

Applied in the portfolio

• Enterprise MCP Gateway — A governed integration layer that turns enterprise APIs into safe, versioned tools for production AI agents.