Tool Registry

What it is

The system of record for the tools an organisation has made callable. Each entry binds a stable name to an input and output contract, an owner, a version, a lifecycle state, and the properties that decide how the tool may be used — whether it mutates anything, whether a repeat is safe, what class of data it touches. Entries change through a release process rather than at runtime, and they outlive the agents, models, and protocols that happen to call them.

Why it matters

As soon as more than one team can add a tool, the set of callable actions stops being knowable by reading code. Questions that governance and incident response ask constantly — which tools can move money, who owns the refund action, what breaks if an argument becomes required — have no answer without a catalogue that is authoritative rather than merely descriptive. The registry is also where facts other controls depend on get recorded once: a permission rule, a retry policy, and an isolation decision all need to know what kind of thing a tool is, and none of them should be inferring it from a docstring.

Why it is not tool discovery

A registry is curated, owned, and changed deliberately. Discovery reads whatever is being advertised at this moment, including by servers nobody on your team operates. The two sets diverge in both directions: something can be discoverable and unregistered, such as an endpoint a developer connected last week, or registered and currently undiscoverable because its service is down. Treating the runtime enumeration as the catalogue gives you a record that changes without review; treating the catalogue as runtime truth gives you calls to things that are no longer there.

Key decisions

• Who holds naming authority, and whether names are globally flat or namespaced by owning team or backing system. Flat names are easier for a model to choose between and much harder to govern.
• Whether the catalogue is read on the call path or compiled into each deployment at build time. Serving from it makes changes immediate and places it in the blast radius of every invocation.
• Which metadata is mandatory at registration rather than optional: effect class, idempotency, data sensitivity, owner, expected latency. Optional fields are left empty.
• How a contract may change — additive only, parallel versioned entries, or coordinated breaking releases — and how long a superseded entry remains callable afterwards.
• The admission bar for a new entry: self-service publication, platform-team review, or evidence such as a passing example invocation and a named on-call owner.

Failure modes

• Two teams register the same verb with different semantics. One archive hides a record, the other deletes it, and callers cannot tell which one they reached.
• The entry describes the contract as intended and the implementation has since moved on, so the catalogue becomes documentation that is confidently wrong.
• A tool is marked deprecated in the catalogue and stays callable for years, because nothing enforces lifecycle state at the point of invocation.
• Descriptions are written for a developer browsing a portal page, so the one field a model relies on to choose between two similar entries reads "see internal wiki".
• Several hundred entries accumulate with no curation, and every consumer builds its own private allowlist to stay usable — at which point the catalogue governs nothing.
• Ownership is recorded as a team name that a reorganisation dissolved, so a breaking change ships with nobody to notify and no one to answer the page.
• Effect classification is self-declared and never audited, so an entry labelled read-only writes an audit row and a duplicate call doubles it.

Related capabilities

• Tool Discovery — the runtime enumeration this catalogue is not
• Tool Schema Validation — enforces the contract an entry declares
• Tool Permission Management — consumes entry metadata to decide
• Function Calling — turns selected entries into declarations a model sees
• MCP Server — one way a registered tool is actually exposed to callers

Applies: Production readiness · Design questions