Adding a Built-In Hermes Tool

Most custom capabilities should be a skill or plugin. A built-in tool is appropriate only when the capability belongs in Hermes core and needs first-class schemas, binary or streaming behavior, credential integration, or shared runtime support.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-tools

Tool contract

A built-in tool module provides an availability check, a handler, a JSON schema, and a registry call. Hermes discovers modules that register at import time. The tool must also belong to the appropriate toolset so users and platform configurations can actually enable it.

Handlers should accept a dictionary of validated arguments, return a serializable result, and express failures as useful error data. Stateful tools may need the task identifier supplied by dispatch. Async handlers should use the registry's async support rather than starting unmanaged event loops.

Implementation checklist

• Confirm the capability cannot be expressed as a skill.
• Prefer a plugin when core modification is unnecessary.
• Define a narrow name, description, and JSON schema.
• Add a truthful availability check and dependency list.
• Return structured success and error results.
• Register the handler in the correct toolset.
• Add secret setup metadata without logging secret values.
• Test discovery, availability, dispatch, failure, and one live smoke path.

Pitfalls

• Writing a core tool for a workflow that existing tools and instructions already cover.
• Registering the module but forgetting toolset membership.
• Throwing raw exceptions that lose actionable context.
• Calling asyncio.run() inside a managed async dispatch path.
• Bypassing approval controls for dangerous operations.

Verification steps

1. Start Hermes without the optional dependency and confirm the tool reports unavailable cleanly.
2. Install or configure the requirement in a test profile.
3. Inspect the exposed schema.
4. Invoke the handler with valid and invalid arguments.
5. Test a missing-credential error without exposing the credential.
6. Run the focused registry and toolset tests.
7. Ask an agent to use the tool in a harmless end-to-end request and inspect the stored tool call.