liveBook · Manning

Tool registry

As explained in Designing AI Systems

A tool registry is a managed catalog that stores tool definitions and versions, supports discovery, and governs their registration and lifecycle.

A tool registry is the authoritative catalog of platform-managed tools. Instead of embedding separate function definitions in each application, teams register capabilities once and let authorized applications discover and reuse them. The surrounding Tool Service handles execution, validation, and credential injection; the registry organizes the definitions those operations rely on. section 6.1.1 section 6.2

A registration includes a schema, documentation, execution endpoint, and metadata. Metadata can describe behavior such as idempotency, side effects, and rate limits. Discovery returns complete definitions that can be converted into model function-calling formats, including names, descriptions, and parameter schemas. section 6.1.1 section 6.1.3 section 6.9

Listing 6.4 Registering a tool through the SDK
platform.tools.register(
    name="healthcare.scheduling.book_appointment",    #A
    description="Book an appointment slot for a patient",
    parameters={
        "patient_id": {"type": "string", "description": "Patient identifier"},
        "slot_id": {"type": "string", "description": "Available slot to book"}
    },
    endpoint="https://api.clinic-scheduler.com/v1/bookings",    #B
    behavior={"is_read_only": False, "is_idempotent": False},
    rate_limits={"requests_per_session": 3}    #C
)

This SDK registration defines an appointment-booking tool, its endpoint, behavior, and per-session rate limit. section 6.1.3

Discovery and governance depend on how tools are organized:

  • Use hierarchical names such as healthcare.scheduling.book_appointment to distinguish operations and align ownership with domains. Namespace owners control who can register or modify definitions. section 6.2
  • Filter discovery by the calling application's authenticated identity. Tools outside permitted namespaces do not appear in results. section 6.2
  • Attach capabilities and tags so developers or agents can find tools without knowing their exact namespace. Write specific descriptions that help a model select the right tool. section 6.2.1

The registry maintains version history and allows multiple versions to coexist. Applications can discover tools using version constraints, while registration enforces semantic-version compatibility: breaking changes require a major version. To retire a version, mark it deprecated, provide a sunset date and migration guidance, and allow existing users a grace period. Version diffs help teams inspect changes before migrating. section 6.2.2

Listing 6.10 Version-constrained tool discovery
tools = platform.tools.discover(
    namespace="healthcare.scheduling.*",
    version_constraint="^1.0.0"    #A
)
 
tools = platform.tools.discover(
    namespace="healthcare.scheduling.*",
    version_constraint=">=1.0.0 <3.0.0"    #B
)

Version-constrained discovery lets applications migrate on different schedules rather than updating simultaneously. section 6.2.2

How Designing AI Systems covers it

How deep it goes
Details registration, access-filtered discovery, semantic-version compatibility, and deprecation through service and SDK interfaces.
Examples
Uses appointment-booking and insurance tools to illustrate registration, namespace discovery, capability tags, and version migration.
What you can do after
Operate/configure a tool registry through SDK registration, discovery filters, version constraints, and deprecation operations.
How it connects
Connects the registry to function calling, access control, semantic versioning, and the Model Context Protocol.

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 Systems. The section links point to the parts of the book it draws on.