Tool Registry — Patterns

The contract is the registered artefact

Problem. When an entry stores a pointer to the code that implements a tool — a module path, a repository link — the catalogue cannot answer anything about the contract without resolving that pointer, and the contract silently changes whenever the code does.

Approach. Register the schema document itself, byte for byte, along with its governance fields, and have the implementation assert at startup that it satisfies the registered contract rather than the other way round. A deployment whose code no longer matches its entry fails to start instead of serving a surprise.

Trade-off. Authors now maintain a declaration separately from the function signature and will resent the duplication. Generating the declaration from code and committing the generated file keeps one source of truth while preserving a reviewable diff, but it only works where the generator can express the governance fields.

Lifecycle state with an enforced clock

Problem. Deprecation recorded only as a catalogue field is advice. Consumers ignore it because nothing stops them, and entries marked superseded three years ago are still the most called tools in the fleet.

Approach. Make lifecycle state a value the invocation path reads: experimental entries resolve only for callers that opted in, deprecated entries resolve but emit a warning attributed to the calling service, and retired entries fail with a message naming the replacement. Attach a date to each transition at the moment of the previous one, so the clock starts without a second human decision.

Trade-off. Enforcement means the catalogue is now load-bearing at call time, with the availability consequences that follow. It also produces a real deadline that someone must be empowered to extend, or teams will route around the registry entirely.

Effect classification as an admission requirement

Problem. Retry policy, approval rules, and sandbox placement all need to know whether a tool mutates state and whether a repeat is safe. When the field is optional, the majority of entries leave it blank and every downstream control defaults to its most permissive setting.

Approach. Refuse registration without an explicit effect class and an idempotency declaration, with no default value available. Where the author claims read-only, require the claim to be testable — a documented call that can be executed twice in a verification environment and compared. Record the declaration as part of the versioned entry so a change to it is a reviewable event.

Trade-off. It slows registration and will be argued about, particularly for tools whose backing system logs reads. The classification is still self-asserted; the gain is that it is asserted deliberately, dated, and attributable, not that it is proven.

Signed catalogue snapshots for consumers

Problem. If every caller queries the live catalogue, the registry becomes a hard runtime dependency for all tool use. If every caller caches independently, the fleet runs on an unknown mixture of catalogue versions and a deprecation can never be confirmed complete.

Approach. Publish the catalogue as an immutable, versioned, signed snapshot on a regular cadence and on demand. Consumers pin a snapshot identifier, report it in telemetry, and upgrade as a deliberate act. "Which snapshot is each service on" becomes a dashboard rather than a guess, and the live store can be unavailable without stopping tool calls.

Trade-off. Urgent removals — a tool that must stop being callable now — need a separate fast path, typically a small revocation list consulted on every call. That list is then the availability-critical component the snapshot was meant to avoid, only much smaller.