Register tools

Everything the model can reach lives in a ToolCatalog: local functions, upstream MCP servers' tools, or both, ranked as one surface. This page covers local tools; upstream servers are on Register MCP servers.

The anatomy of an executable tool

An executable tool pairs the metadata Ratel indexes with the handler that runs it. Registering a local tool is one register call:

from ratel_ai import ExecutableTool, ToolCatalog

catalog = ToolCatalog()
catalog.register(
    ExecutableTool(
        id="read_file",
        name="read_file",
        description="Read a file from local disk and return its textual contents.",
        input_schema={
            "type": "object",
            "properties": {"path": {"type": "string", "description": "absolute path to the file"}},
            "required": ["path"],
        },
        output_schema={"type": "object", "properties": {"contents": {"type": "string"}}},
        execute=lambda args: {"contents": open(args["path"]).read()},
    )
)

What each field is for:

• id — the stable handle everything else uses: catalog.invoke(id, args), the toolId the model passes to invoke_tool, and the toolId on every search hit. Unique per catalog; MCP-ingested tools get a server-namespaced id automatically.
• name — the tool's name where it appears as a direct tool definition, e.g. when you pre-filter top-K hits into the model's tool list.
• description — what the model reads to pick the tool, and the main text BM25 ranks against. This is the field that decides whether the tool is ever found; see the definition-writing guidance in Keyword search.
• input_schema / output_schema — JSON Schema for the arguments and the result. The input schema rides every search_capabilities hit, so the model can call the tool without a second lookup. Both default to {}.
• execute — the handler, sync or async. catalog.invoke awaits it either way and rethrows whatever it throws (after recording an invoke_error trace event), so failures surface where you call it. register raises ValueError if execute is None.

The ToolCatalog surface

The catalog is the registry plus an executor per tool. The methods you will use:

import asyncio

from ratel_ai import ExecutableTool, ToolCatalog


async def main() -> None:
    catalog = ToolCatalog()                 # ToolCatalog(trace=None, method="bm25")
    catalog.register(                       # metadata + execute
        ExecutableTool(
            id="echo",
            name="echo",
            description="Repeat a message back to the caller.",
            input_schema={"properties": {"text": {"type": "string"}}},
            output_schema={"properties": {"text": {"type": "string"}}},
            execute=lambda args: {"text": args["text"]},
        )
    )
    hits = catalog.search("repeat a message", 5)  # → list[SearchHit]
    assert hits[0].tool_id == "echo"
    catalog.build_embeddings()              # pre-compute semantic/hybrid embeddings
    assert catalog.has("echo")              # → bool
    assert catalog.get("echo") is not None  # → Tool | None
    assert catalog.get_executable("echo") is not None
    print(await catalog.invoke("echo", {"text": "hello"}))
    catalog.drain_trace_events()             # → list[dict]; memory sink only

asyncio.run(main())

invoke calls the handler, awaits it only if it returned a coroutine (so sync and async executors both work), and re-raises whatever it throws after recording an invoke_error trace event. search defaults to origin="direct"; pass catalog.search(query, k, "agent") to tag a search as model-initiated in telemetry.

Two constructor keywords: trace= wires a local trace sink (default: none), and method= sets the catalog's default retrieval method (default "bm25"). The per-call override lives on Use the discovery tools; how the engines rank is on Semantic & hybrid search.

Build the embedding cache

BM25 needs no preparation. Semantic and hybrid retrieval rank against a pre-built embedding cache — a search embeds only the query, never the corpus — so the cache must cover every tool before the first such search. Two ways to keep it current:

# Eager: a semantic- or hybrid-default catalog embeds every tool as it is
# registered. Nothing else to call; a model-load failure raises at register.
eager = ToolCatalog(method="hybrid")

# Explicit: a BM25-default catalog embeds nothing until you ask. Build the
# cache after registering, then opt in per call.
lexical = ToolCatalog()
# ...register tools...
lexical.build_embeddings()  # synchronous; raises RuntimeError if the model fails to load
lexical.search("rotate the api key", 5, method="semantic")

build_embeddings() is incremental and keyed by id: it embeds only what is missing, so adding or re-registering one tool costs one embedding, not N, and a call with nothing left to embed is a no-op. Re-registering a tool invalidates its cached vector — on an explicit catalog, build again before the next semantic or hybrid search. A search over an incomplete cache raises instead of silently embedding the corpus.

The first embedding loads the bundled local model (BAAI/bge-small-en-v1.5) in-process, downloading it into the HuggingFace cache on first use — no service, no API key. The model's footprint, offline use, and when the engines are worth it are on Semantic & hybrid search.

ToolRegistry: ranking without execution

Need only the ranking, and you will dispatch tool calls yourself? ToolRegistry is the metadata-only BM25 index underneath ToolCatalog, with no executors and no capability tools. It takes positional metadata rather than a dataclass:

from ratel_ai import ToolRegistry

registry = ToolRegistry()
registry.register(
    "read_file",
    "read_file",
    "Read a file from local disk and return its textual contents.",
    {"properties": {"path": {"type": "string"}}},
    {"properties": {"contents": {"type": "string"}}},
)

registry.search("read a text file", 5)
# → [SearchHit(tool_id="read_file", score=1.42), ...]

SkillRegistry is the same executor-free index over skills: register(id, name, description, tags, tools, metadata, body), with hits as SkillHit (.skill_id, .score). Both registries also expose search_with_origin, search_with_method, build_embeddings, and the trace-sink plumbing (set_trace_sink, record_event, drain_trace_events) that the catalogs build on.

Spot-check what you registered

Verify a registration the way the model will find it: run a direct search and check that the expected ids surface. Local and upstream tools rank together.

hits = catalog.search("read a text file from disk", 5)
for hit in hits:
    print(hit.tool_id, hit.score)
# read_file 2.1
# fs__read_file 1.8

This is the same ranking search_capabilities runs on the model's behalf — a direct catalog.search is tagged origin: "direct" in telemetry, the capability tool's searches "agent". If a tool you expect near the top doesn't surface, the fix is almost always its wording, not the ranking.

Next steps