liveBook · Manning

Tool registry

As explained in Designing AI Agents

A collection of tools available to an agent, together with information needed to identify or invoke them.

A tool registry is a collection of tool specifications available to an agent. It belongs to the harness around the model: the model may select an action at runtime, but the harness controls which capabilities are exposed and how a selected call reaches execution. section 6.3.3 section 1.1

A tool specification can identify a tool by name and description while recording its effect class, permitted roles and stages, argument validator, and protected arguments. The runtime supplies granted effects; the registry does not create those grants. Registration rejects duplicate names, and eligibility filters specifications against the current role, stage, and granted effects. section 6.3.3

Listing 6.6 Computing the eligible tool surface
class ToolRegistry:
    def __init__(self) -> None:
        self.specs: dict[str, ToolSpec] = {}
 
    def register(self, spec: ToolSpec) -> None:
        if spec.name in self.specs:
            raise ValueError(f"duplicate tool: {spec.name}")
        self.specs[spec.name] = spec
 
    def eligible(self, context: DispatchContext) -> list[ToolSpec]:
        return [
            spec
            for spec in self.specs.values()
            if context.role in spec.roles
            and context.stage in spec.stages
            and spec.effect in context.granted_effects
        ]
 
    def summaries(self, context: DispatchContext) -> list[dict[str, str]]:
        return [
            {"name": item.name, "description": item.description}
            for item in self.eligible(context)
        ]

The registry stores specifications by name, filters them against dispatch context, and returns name-and-description summaries rather than callable functions. section 6.3.3

The eligible set gives a selector fewer irrelevant or impermissible choices. Selection can use a model response, semantic router, rule, or human choice, but a plausible tool name alone does not authorize execution. Eligibility rules must remain synchronized with roles and task state; discovery neither grants authority nor proves tool quality. section 6.3.3

After selection, a dispatch chokepoint rechecks eligibility and validates a stable argument snapshot. It compares protected values with runtime-resolved evidence and binds freshness to the same object and business version. Validators must enforce exact application types: for example, a Python money validator must explicitly reject a Boolean rather than accept it as an integer. section 6.3.3

Protecting a payroll transfer

Both employee_id and amount_cents are protected arguments, resolved from the approved payroll record rather than chosen by the model. For a state-changing effect, the runtime also issues and reuses the commit identity for the same business operation, preventing the agent from creating a fresh attempt merely by inventing another identifier. section 6.3.3

Admission is an enforcement boundary only if it lies on the agent's sole execution path. Direct runner imports, unrestricted shell commands, or alternate API access can bypass it. Structured schemas can catch malformed input or output, but schema conformance does not establish that a protected value is true, current, or permitted. section 6.3.3

Registry and guarded execution

Argus uses the registry to own the candidate surface and requires every executable tool to have a matching guarded binding. Dispatch admits the call; the guarded executor supplies preconditions, a runner, and postconditions, and the resulting action attempt is retained. A guarded Python callable demonstrates this ordering, but is not an operating-system sandbox. section 6.8

How Designing AI Agents covers it

How deep it goes
Implements registration and context-based eligibility, then details admission checks and the limits of the execution boundary.
Examples
Uses a protected payroll transfer and an Argus action facade with registered guarded tools.
What you can do after
Builds a registry and dispatch boundary from scratch, with context filtering and checks on selected calls.
How it connects
Connects tool registries to permission gates, tool dispatch, argument validation, guarded execution, and action traces.

Also explained in

Compare how 4 books explain tool registry →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Agents. The section links point to the parts of the book it draws on.