Understand the Hermes Tools Runtime

Follow a Hermes tool from self-registration and toolset filtering through availability checks, central dispatch, hooks, and structured error handling. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

Built-in tools self-register at import time through the central registry. Discovery scans tool modules for top-level registration calls, then model tooling builds the schemas visible to the model.

Each tool entry has a unique name, toolset, schema, handler, optional availability check, async flag, and display metadata. Later name collisions win, so names must be deliberate.

Toolsets are resolved before definitions are sent to the model. Availability checks then remove tools whose credentials or dependencies are missing, and selected schemas may be patched to mention only tools that survived filtering.

At runtime, calls pass through pre-hooks, registry dispatch, sync or async execution, structured error wrapping, and post-hooks. A few stateful agent-loop tools are intercepted before ordinary dispatch.

Practical checklist

Register tools at module level so discovery can find them.
Make availability checks cheap, deterministic, and side-effect free.
Keep schemas aligned with handler validation.
Return serializable results and test sync and async paths.
Review approval behavior for shell-like or destructive operations.

Common pitfalls

Hiding registration inside a function that AST discovery never imports.
Using the same tool name in multiple modules unintentionally.
Assuming schema validation replaces handler-side validation.
Throwing raw exceptions and relying on the model to infer what happened.

Verification steps

List tool definitions for the intended enabled and disabled toolsets.
Confirm unavailable dependencies remove only the affected tool.
Dispatch valid, invalid, sync, and async calls.
Inspect pre/post hook behavior and ensure failures return structured errors rather than crashing the agent.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/tools-runtime