Skip to main content

Tool Registry & Discovery

As an agent gains capabilities, two problems appear: the harness needs a single source of truth for what tools exist, and the context window can't hold a hundred verbose tool schemas at once. The registry solves the first; discovery — loading only the relevant tools per turn — solves the second.

Every tool definition you put in context costs tokens and dilutes attention. Ten tools is fine; two hundred is a Tool Junk Drawer that degrades every decision. Discovery is how a large toolset stays usable.

Structure​

The registry holds every tool; only a relevant subset's schemas are surfaced into context, expanded on demand when the model needs more.

How It Works​

  1. Register — each tool declares a name, description, schema, and metadata (cost, permissions, category) in one catalog.
  2. Scope per turn — instead of exposing all tools, select the subset relevant to the current turn's work.
  3. Defer schemas — surface lightweight names/summaries first; load full schemas only when a tool is actually selected, keeping the window lean.
  4. Discover on demand — let the model search the registry for a capability ("find a tool that sends email") and pull its schema in when matched.
  5. Validate against the registry — dispatch checks every call against the catalog, so unknown or out-of-scope tools are rejected cleanly.

Key Characteristics​

  • One catalog, many consumers — dispatch, permissions, and tracing all read from the same registry, so a tool is defined once.
  • Schemas are context cost — full definitions are expensive; load them lazily. The cheapest token is the one you didn't include.
  • Scoping improves decisions — a focused toolset makes the model's choice easier and more accurate than a wall of options.
  • Discovery scales the toolset — search-on-demand means adding the 201st tool doesn't degrade the other 200.
  • Metadata enables governance — per-tool cost and permission tags let the harness reason about what a call will cost and whether it's allowed.

Pitfalls​

  • Exposing every tool every turn — floods the window, raises cost, and worsens selection. The Tool Junk Drawer in its purest form.
  • No single source of truth — tool definitions scattered across the codebase drift out of sync with what dispatch actually accepts.
  • Over-scoping — hiding a tool the task genuinely needs forces the model to improvise badly. Discovery must be able to surface it.