Designing a Tool Registry

An agent with forty tools pasted into every prompt is a common failure pattern. The model picks the wrong tool, a provider changes its response shape and the agent breaks at 2 a.m., and nobody knows who owns the broken integration. Teams rebuild the same API wrapper three times because no catalog records that it already exists.

This is tool sprawl: tools multiply across prompts, notebooks, and team wikis with no shared source of truth. The symptoms are consistent:

• Wrong selection: the model chooses a near-duplicate tool because nothing distinguishes them.
• Silent breakage: a provider changes its schema; the agent keeps parsing the old shape.
• No ownership: a failing tool has no accountable team, so it stays broken.
• Duplicated wrappers: each team integrates the same API independently.

A tool registry attacks all four symptoms at once. It is a single catalog where every tool is a record carrying its schema, description, owner, version, and rate limits. Agents discover tools from the registry instead of hardcoded prompt lists, and every integration has exactly one owner.

Before continuing, make sure you understand defining tools for LLMs — the registry assumes tools already have names, descriptions, and parameter schemas. The registry adds the operational metadata around them.

Once the registry exists, the next problem is keeping selection accurate as the catalog grows. That is the subject of tool selection under many options.

Every tool in the registry is one record. The record has to answer four questions: what does the tool do, what does it accept, who owns it, and how often may it be called?

from dataclasses import dataclass, field
from typing import Any

@dataclass
class ToolRecord:
    name: str
    description: str
    input_schema: dict[str, Any]
    owner: str
    version: str
    rate_limit_per_min: int
    domains: list[str] = field(default_factory=list)

The registry itself is a thin store around these records:

class ToolRegistry:
    def __init__(self) -> None:
        self._tools: dict[str, ToolRecord] = {}

    def register(self, record: ToolRecord) -> None:
        if record.name in self._tools:
            raise ValueError(f"{record.name} is already registered")
        self._tools[record.name] = record

    def discover(self, domains: list[str]) -> list[ToolRecord]:
        return [t for t in self._tools.values() if set(t.domains) & set(domains)]

discover is the load-bearing method: an agent asks for the tools in its current domain and gets a scoped subset instead of the full catalog.

Two fields deserve emphasis. description is read by the model on every selection decision, so it carries the same weight as the schema itself — see defining tools for LLMs for what makes one effective. owner is what makes breakage fixable: when a tool fails, the registry routes the incident to a team instead of a wiki page nobody reads.

A schema that changes without a version is a schema that breaks agents silently. Treat the input schema like a public API and version it with semantic versioning.

The check that matters is whether prompts written against the old schema still work against the new one:

def is_backward_compatible(old_schema: dict, new_schema: dict) -> bool:
    old_required = set(old_schema.get("required", []))
    new_required = set(new_schema.get("required", []))
    return new_required <= old_required

Existing prompts supply everything the old schema required. If the new schema requires more, those prompts break — so the new required set must be a subset of the old one. Anything else is a major bump, and the registry should refuse to register it under the same version.

Domain grouping solves a different problem: an agent handling refunds should not see the weather tools. Tag every record with domains and let discover filter, as shown in the previous chapter. This keeps the model's decision space small, which directly improves selection accuracy — the core idea behind tool selection under many options.

Providers drift. A tool that returned temp_c last quarter returns temperature this quarter, and the agent parses None until someone notices. The registry's last job is to catch that drift at the boundary, before it reaches the model.

Declare an output schema alongside the input schema, then validate every response against it:

from pydantic import BaseModel, ValidationError

class WeatherOutput(BaseModel):
    temperature: float
    conditions: str

def validate_response(tool_name: str, payload: dict) -> bool:
    output_model = REGISTRY.output_schemas[tool_name]
    try:
        output_model(**payload)
        return True
    except ValidationError:
        return False

When validation fails, the agent receives a structured error instead of garbage, and the tool's owner gets an alert. Input validation matters for the same reason — see JSON handling and Pydantic models for the validation patterns.

Failure modes this boundary check prevents:

• Silent shape drift: the provider renames a field; the agent keeps running on stale parsing logic.
• Partial responses: an error page returns HTTP 200 with an HTML body; without schema validation the agent treats it as data.
• Cascading retries: the model retries a call that was never valid, burning tokens on a response that cannot parse.

A registry without boundary validation is a catalog that lies. The schema is a contract; enforcing it on the way out is what makes the contract real.