Model Capability Registry

What it is

A machine-readable record of what each model admitted to the estate can actually do: context window, maximum output length, accepted modalities, tool-calling and structured- output support, tokenizer family, price per input and output token, typical latency class, hosting region and data-handling terms, and retirement date. It is a data asset that other components query, not a behaviour of its own.

Why it matters

Every interesting decision elsewhere is a predicate over these facts. A routing rule asks whether a model accepts images. A budget calculation asks for a context ceiling and a price. A fallback chain asks whether the alternate target supports tool calls. Without a registry each of those questions is answered by a constant embedded in some file, and those constants are wrong within a quarter — prices change, context windows are extended, models are retired. The registry is what makes "add a model" a data change instead of a hunt through the codebase.

Why declared facts are not enough

Two kinds of fact live here and they age differently. Declared facts come from the provider's documentation and change when the provider says so. Observed facts — measured p95 latency, real maximum sustained throughput, whether strict schema mode actually holds under your prompts — come from your own traffic and change continuously. Conflating them produces a registry that is confidently wrong about the half that matters most.

Key decisions

• What the authoritative source is for each field, and whether the registry is maintained by hand, synchronised from provider APIs, measured by probe, or some combination per field.
• How an entry is admitted and withdrawn: who approves a new model for production use, and what makes an entry unavailable without deleting its history.
• How stale an entry may be before it is distrusted, and what the system does with a stale entry — refuse, warn, or proceed.
• Whether the registry is read at runtime on the request path or compiled into deployments, which trades freshness against an availability dependency.
• Whether non-technical attributes belong here — processing region, retention terms, approval status for regulated workloads — or in a separate governance record that references the same identifiers.

Failure modes

• Prices are hard-coded in a cost dashboard and in the registry, diverge after a provider change, and two systems report different spend for the same traffic.
• A context window is recorded from an announcement but the deployed account tier permits less, so requests sized against the registry fail at the provider.
• "Supports tool calling" is a boolean, but the models behind it differ on parallel calls, nested schemas, and required-field enforcement, so a fallback target that satisfies the boolean still breaks the agent.
• Entries accumulate for models nobody uses and nobody verifies, so the registry's average accuracy declines even while the entries in active use are fine.
• The registry becomes a runtime dependency with no cache, and its outage stops every model call in the organisation for a lookup that changes once a month.
• Retirement dates are recorded at admission and never refreshed, so a shortened deprecation window is not noticed until the endpoint returns errors.

Related capabilities

• Model Routing — rules are predicates over these fields
• Model Fallback — uses it to check an alternate target is actually equivalent
• Model Versioning — retirement dates and version identities are registry fields
• Token Budget Management — reads context ceilings and prices from here
• Model Benchmarking — produces the observed facts the registry stores alongside declared ones

Applies: Production readiness · Design questions