---
id: "concept-metadata-first-tool-registry"
type: "concept"
source_timestamps: ["00:05:31"]
tags: ["system-design", "tool-calling"]
related: ["concept-dynamic-tool-pool-assembly", "action-build-metadata-registry", "entity-claude-code"]
definition: "Defining agent tools and capabilities as queryable data structures before writing any execution logic to enable safe introspection and runtime filtering."
sources: ["s46-anthropic-25b-leak"]
sourceVaultSlug: "s46-anthropic-25b-leak"
originDay: 46
---
# Metadata-First Tool Registry

## Definition
Defining agent tools and capabilities as **queryable data structures** before writing any execution logic, so the system can introspect and filter capabilities without triggering side effects.

## What [[entity-claude-code-d46|Claude Code]] Does
[[entity-claude-code-d46|Claude Code]] uses a metadata-first design rather than tightly coupling tool definitions with execution logic. Capabilities are defined as data structures upfront. This registry acts as a single source of truth, answering *"what exists"* and *"what does it do"* without executing anything.

In the leaked codebase this manifests as **two parallel registries**:

- **Command registry** — 207 entries for user-facing actions.
- **Tool registry** — 184 entries for model-facing capabilities.

Each entry behaves like a dictionary containing:
- a **name**
- a **source hint**
- a **responsibility description**

## Why It Matters
This separation is the foundation that makes other primitives possible:

- It allows the system to **filter tools by context** — see [[concept-dynamic-tool-pool-assembly]].
- It permits **introspection of capabilities without triggering side effects**.
- It enables **safe, on-demand tool loading**.

Without this foundation, developers cannot implement runtime filtering or safely orchestrate new tools — every tool reference becomes a potential live wire.

## Action
See [[action-build-metadata-registry]] for the practitioner step.

## Validation (Enrichment)
Validated as common practice in agent toolkits like LangChain (tool schema registry) and OpenAI function calling, both of which use JSON schemas for safe filtering. This is among the better-corroborated primitives in the source.


## Related across days
- [[concept-tool-selection-error]]
- [[concept-dynamic-tool-pool-assembly]]
- [[concept-skills-as-contracts]]