Tool Registry
Every agent in Ishvana has a set of tools — local functions a Divinity Engine handler can invoke to gather project context or perform bounded work. Hawken has tools for lore search, document fetch, and style analysis. Lagan has tools for web research, URL analysis, and Wikipedia lookup. Lorekeeper has tools for entity extraction and canon lookup. The Tool Registry is Etherforce’s catalog for those tool surfaces: one central place where every tool is registered, validated, tracked, and exposed to observability. It’s one of the least visible parts of Etherforce, and it has a disproportionate impact on reliability.
What the registry is
Section titled “What the registry is”The Tool Registry is a singleton service that every agent registers its tools with on startup. When the engine starts, the boot coordinator calls each agent’s register_tools() method, which hands the tool definitions to the registry. Every tool has:
- A name (unique across all agents).
- A description (what the tool does).
- A parameter schema (what the tool takes as arguments, in JSON schema format).
- The agent that owns it (so the registry knows which agent gets credit for the tool).
- An implementation function (the actual code the tool executes when called).
Once registered, the tool is available for any agent to call — though in practice each agent only sees its own tools unless explicitly told otherwise.
Stable registration order
Section titled “Stable registration order”The most important thing the registry does isn’t merely holding the tool definitions. It’s making sure the tool list is sorted in a stable, deterministic order across every handler dispatch.
Here’s why that matters.
Deterministic local handlers are easier to test when their inputs are stable. If two dispatches have the same handler arguments and the same tool surface, the registry should expose those tools in the same order every time. That makes handler envelopes easier to diff, benchmark fixtures easier to compare, and observability logs easier to read.
Before the Tool Registry, Ishvana had this problem constantly. Every request had its tool list built dynamically from whichever agent was active, in whatever order the agent’s executor happened to iterate its tool functions. The order was undefined, so traces drifted across runs even when behavior was otherwise identical.
The Tool Registry fixes this by sorting every tool list alphabetically by tool name before it is attached to a handler dispatch. Same tools every request means same order every request, which keeps diagnostics and benchmarks reproducible.
Observability through the registry
Section titled “Observability through the registry”The second job of the registry is observability. Because every tool is registered in one place, Etherforce can track invocation counts per tool, per agent, across sessions. The Tool Registry tab in the Analysis workspace shows exactly this — a full table of every tool every agent has registered, with columns for name, description, parameter count, and total invocations.
The invocation counts are useful for:
- Unwired tool detection. If a tool shows zero invocations after a month of heavy use, something is wrong. Either the tool is broken, the owning handler never reaches it, or the feature that should call it is unfinished. Any of those is worth investigating.
- Hot tool identification. Tools with disproportionately high invocation counts are worth optimizing. If Hawken’s “lore_search” tool is called 200 times a day, its implementation’s latency matters more than a tool called 2 times a day.
- Per-agent distribution. Which agents are calling which tools. A tool registered for Hawken but being called by Lagan means something unexpected is happening — either the tool is being called by the wrong agent, or the tool’s scope is broader than originally intended.
The observability data is cheap to collect because it’s literally a counter that increments every time the tool’s implementation function is called. No extra instrumentation required.
Parallel delegation and the tool list
Section titled “Parallel delegation and the tool list”One of Ishvana’s more advanced features is parallel delegation — when Ishvana (the orchestrator) fires multiple specialist handlers simultaneously on a multi-domain request. Parallel delegation uses a local dispatch path that takes an array of {agent, task, context} objects and runs each one concurrently.
The parallel dispatch surface lives in the registry like any other tool, and it’s registered to Ishvana specifically. When Ishvana decides to use it, the implementation fans out to the specialist agents concurrently and returns their combined results.
The whole parallel-delegation capability depends on the registry, because the registry is where the specialist agents’ local interfaces are declared. Ishvana cannot call into a specialist route unless the registry knows what that route accepts and returns.
Streaming handler progress
Section titled “Streaming handler progress”A smaller but meaningful detail: long-running handlers can emit progress chunks through Etherforce while their tools are still working. The UI does not have to wait for the entire operation before it can show which stage is running.
This matters because many local operations are staged. A research request might fetch cached bookmarks, inspect Legendry matches, pull a Wikipedia page, and then synthesize findings. Streaming progress tells you which part is active and gives the observability panel meaningful timing slices.
For a handler that runs three local tools, the useful question is no longer “which provider streamed fastest?” It is “which stage took time, did it hit cache, and did the handler return the expected structured fields?” The registry gives Etherforce the tool names it needs to answer that.
The registry isn’t magic
Section titled “The registry isn’t magic”A few things worth noting:
- Tools aren’t hot-swappable. Once Etherforce is running with a registered tool list, you can’t add new tools mid-session. If you want to add a new tool, you restart the engine.
- Tool names must be unique across all agents. Two agents can’t both register a tool called
search. If you’re writing a custom skill that adds a tool, make sure the name is distinctive. - Parameter schemas are validated. A tool implementation that doesn’t match its declared parameter schema will fail before the owning handler can use it reliably. Etherforce validates implementations against schemas at registration time.
- The registry is singleton per project. There’s one registry instance for the whole Ishvana app. Different projects share the same registry — which means different projects see the same tools.