Understanding the Toolset System in Hermes Agent: Platform-Based Tool Grouping

The toolset system in Hermes Agent organizes external capabilities into named collections called toolsets, where a shared core set is available to all platforms while platform-specific toolsets restrict or extend functionality based on the runtime environment (CLI, Telegram, Discord, etc.).

The NousResearch/hermes-agent repository implements a modular architecture where every external capability—whether file system access, web search, or terminal execution—is encapsulated as a tool. These tools are not loaded arbitrarily; instead, the toolset system in Hermes Agent groups them into logical collections and assigns them per platform to ensure security and compatibility.

Core Architecture of the Toolset System

The system operates on a two-tier hierarchy: a universal core that every platform receives, and platform-specific extensions that add or remove capabilities based on the execution context.

The Core Toolset (_HERMES_CORE_TOOLS)

All platforms share a common foundation defined as _HERMES_CORE_TOOLS in the codebase. According to the source documentation at AGENTS.md#L31, this core includes generic utilities such as file tools, web tools, vision tools, and the terminal sandbox. These tools are considered safe and essential across all runtime environments, from local CLI to cloud-based messaging platforms.

Platform-Specific Toolset Definitions

Beyond the core, individual platforms receive tailored toolsets defined in toolsets.py. Each platform identifier maps to a specific list of tools that make sense for that environment. For example, the local CLI receives clipboard access and unrestricted terminal tools, while web-facing platforms receive sandboxed versions or omit certain capabilities entirely.

Platform-Specific Toolset Breakdown

The toolsets.py file defines a named collection for each runtime environment. The following table summarizes how tools are grouped per platform:

Platform	Toolset Name	Contents
hermes-cli	hermes-cli	CLI-only tools (e.g., local terminal, clipboard)
hermes-telegram	hermes-telegram	Full suite including terminal sandbox (run in Docker)
hermes-discord	hermes-discord	Same as Telegram – all tools enabled
hermes-whatsapp	hermes-whatsapp	Full suite of tools
hermes-slack	hermes-slack	Full suite of tools
hermes-homeassistant	hermes-homeassistant	Home Assistant integration tools
hermes-gateway	hermes-gateway	Meta-toolset aggregating all platform toolsets

The Gateway Meta-Toolset

The hermes-gateway platform serves a special role as a meta-toolset. According to AGENTS.md#L492-L500, this configuration aggregates all platform toolsets, making it useful for development or scenarios requiring maximum capability. Unlike other platforms that restrict tools, the gateway intentionally broadens the scope.

Configuration and Runtime Loading

When the agent initializes, the toolset selection process follows a specific chain through three critical files.

First, hermes_cli/config.py selects the appropriate toolset based on the platform argument passed during startup. This configuration maps string identifiers like "hermes-telegram" to their respective toolset definitions.

Next, model_tools.py discovers the actual tool implementations from the central registry. It pulls the appropriate tool definitions based on the selected toolset, preparing them for the LLM context window.

Finally, run_agent.py executes the core agent loop, loading the selected toolset and dispatching tool calls as the LLM requests them. This separation of concerns ensures that toolset logic remains decoupled from the execution engine.

Dynamic Toolset Customization

Developers can override default toolset assignments at runtime via the AIAgent constructor. The class accepts two key parameters: enabled_toolsets and disabled_toolsets, documented at AGENTS.md#L173-L174.

This capability enables fine-grained security controls. For example, you can disable the terminal sandbox in restricted environments while preserving web-search functionality.

from run_agent import AIAgent

# Disable terminal tools for this specific session

agent = AIAgent(
    platform="hermes-gateway",
    disabled_toolsets=["terminal"],   # Removes the sandbox terminal

)

Extending the System with New Tools

Adding a new capability to the Hermes Agent toolset system requires updates to three specific locations, as outlined in AGENTS.md#L663-L714.

First, create the tool implementation file (e.g., tools/example_tool.py). This file defines the function logic and schema.

Second, register the tool in model_tools.py so the agent can discover it during initialization.

Third, add the tool to a toolset definition in toolsets.py—either to the core list (_HERMES_CORE_TOOLS) for universal availability, or to a platform-specific list for restricted access.

The following example demonstrates registering a CLI-only tool:

# tools/my_cli_tool.py

from tools.registry import registry

def my_cli_tool(param: str) -> str:
    return f"Received {param}"

MY_SCHEMA = {
    "name": "my_cli_tool",
    "description": "Demo CLI‑only helper",
    "parameters": {
        "type": "object",
        "properties": {"param": {"type": "string"}},
        "required": ["param"],
    },
}

registry.register(
    name="my_cli_tool",
    toolset="hermes-cli",          # <- limits it to the CLI platform

    schema=MY_SCHEMA,
    handler=lambda args, **kw: my_cli_tool(args["param"]),
    check_fn=lambda: True,
)

This registration pattern ensures the tool appears automatically when the agent runs in CLI mode, but remains hidden from Telegram or Discord sessions.

Key Files in the Toolset Architecture

Understanding the toolset system requires familiarity with five critical files that handle registration, configuration, and execution:

• toolsets.py – Defines the _HERMES_CORE_TOOLS constant and platform-specific toolset mappings.
• tools/registry.py – Central registry where each tool registers its JSON schema and execution handler.
• model_tools.py – Discovers registered tools and builds the tool definition payload sent to the LLM.
• hermes_cli/config.py – Holds user-configurable defaults, including the platform identifier and toolset toggles.
• run_agent.py – Core agent loop that loads the selected toolset and dispatches tool calls.

These files collectively implement the toolset system, ensuring that each Hermes Agent deployment receives only the tools appropriate for its execution environment.

Summary

• The toolset system in Hermes Agent organizes capabilities into named collections, preventing indiscriminate tool loading across platforms.
• _HERMES_CORE_TOOLS provides a universal foundation available to all platforms, including file, web, and vision tools.
• Platform-specific toolsets in toolsets.py restrict or extend capabilities—CLI gets local terminal access, while messaging platforms receive sandboxed versions.
• The hermes-gateway meta-toolset aggregates all platform tools for development scenarios.
• Runtime customization is possible via enabled_toolsets and disabled_toolsets parameters in the AIAgent constructor.
• Adding tools requires updating three locations: the tool file, model_tools.py, and toolsets.py.

Frequently Asked Questions

How does Hermes Agent decide which tools to load for a specific platform?

The agent selects tools based on the platform argument passed during initialization, which maps to a specific toolset defined in toolsets.py. The configuration in hermes_cli/config.py resolves this mapping, and model_tools.py retrieves the appropriate tool definitions from the registry. This ensures that a CLI instance receives local terminal tools while a Telegram instance receives sandboxed alternatives.

Can I disable specific tools without modifying the source code?

Yes, you can dynamically disable toolsets at runtime using the AIAgent constructor parameters. By passing a list to disabled_toolsets, you can remove specific capabilities—such as the terminal sandbox—without editing configuration files. This is documented at AGENTS.md#L173-L174 and enables secure deployments in restricted environments.

What is the difference between the core toolset and platform-specific toolsets?

The core toolset (_HERMES_CORE_TOOLS) contains universal utilities like file I/O, web search, and vision tools that are safe and necessary for all platforms. Platform-specific toolsets extend or restrict this foundation based on environmental constraints. For example, hermes-cli includes clipboard and local terminal tools, while hermes-telegram substitutes the local terminal with a Docker sandbox to prevent unauthorized system access.

How do I add a new tool that only works on the CLI platform?

To create a CLI-specific tool, implement the tool logic in a new file under tools/, register it in model_tools.py, and assign it to the hermes-cli toolset in toolsets.py or via the registry's toolset parameter. As shown in AGENTS.md#L663-L714, this three-step process ensures the tool only appears when the agent runs in CLI mode, remaining hidden from Telegram or Discord sessions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}