HHermes Explained

Tools

Tool Registry

The central registry for tool schemas, handlers, availability checks, and toolset membership.

Importance 5/52 backlinks1 source refs

Tool Registry

What it is

The central registry for tool schemas, handlers, availability checks, and toolset membership.

In plain terms

Picture a hospital’s on-call board: every specialist’s name is posted with what they treat, how to page them, and whether they’re actually on shift right now. The registry is that on-call board for Hermes — one place holding every tool’s instructions, the code that runs it, and a rule for whether it’s currently usable, instead of those details being scattered across the codebase.

Why it matters

Every one of the 69 registered tool declarations lives in tools/registry.py — schema, handler function, availability check, and toolset membership all defined in one place rather than scattered across the codebase. Turn context consults this exact registry when deciding which tools the model can see this turn, and a tool can be registered but still invisible if its availability check fails — a common source of ‘why can’t the agent do X’ confusion. Toolsets are essentially named views over this registry, not a separate system, which is why membership lives right beside the tool definition.

How it works

Each tool file calls registry.register() at import time — once per tool it defines — handing over its name, schema, handler, toolset label, and an optional check_fn that probes whether the tool can actually run right now (tools/registry.py). Check results are cached for about 30 seconds so a repeat probe doesn’t hit Docker or the filesystem on every turn, but the real flake protection is a separate 60-second grace window: when a probe fails soon after it last succeeded — say Docker timing out once — the last known “available” verdict is served instead of the fresh failure, so one blip doesn’t strip a whole toolset from an agent mid-turn. Only a failure that persists past that window gets cached and honored. When the agent needs its tool list, get_definitions() walks the requested names, skips anything whose check just failed, and returns OpenAI-format schemas, applying any last-minute description overrides (such as delegation limits) before sending them out.

A concrete example

A developer wonders why their coding agent suddenly can’t run shell commands.

  1. They check hermes tools and see terminal listed as enabled.
  2. Behind the scenes, the registry’s check for terminal requirements had failed once (a busy Docker daemon) and, outside the grace window, the failure stuck for 30 seconds.
  3. The next turn, the probe succeeds again and the terminal tool reappears in the model’s available list without anyone touching config.

How it connects

This note belongs to the Tools family. Its closest neighboring concepts are: Video Generation, Toolsets, Agent Runtime, Personal OS.

Source evidence

  • vendor/hermes-agent/tools/registry.py:427-438#tools.registry.ToolRegistry.register — Verified Source Map evidence for ToolRegistry. The registry freezes registration inputs into ToolEntry, retaining the handler and check_fn; it exposes only entries whose cached availability probe passes, dispatches synchronous or asynchronous handlers, and normalizes their results.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • No article currently mentions this concept by name/alias often enough to qualify (see mention-mining policy).