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

> Explore the Hermes Agent toolset system and discover how tools are grouped by platform. Learn about shared core tools and platform-specific extensions for enhanced functionality.

- Repository: [Nous Research/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Tags: deep-dive
- Published: 2026-03-09

---

**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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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.

```python
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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/example_tool.py)). This file defines the function logic and schema.

Second, register the tool in [`model_tools.py`](https://github.com/NousResearch/hermes-agent/blob/main/model_tools.py) so the agent can discover it during initialization.

Third, add the tool to a toolset definition in [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/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:

```python

# 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`](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py)** – Defines the `_HERMES_CORE_TOOLS` constant and platform-specific toolset mappings.
- **[`tools/registry.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/registry.py)** – Central registry where each tool registers its JSON schema and execution handler.
- **[`model_tools.py`](https://github.com/NousResearch/hermes-agent/blob/main/model_tools.py)** – Discovers registered tools and builds the tool definition payload sent to the LLM.
- **[`hermes_cli/config.py`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/config.py)** – Holds user-configurable defaults, including the platform identifier and toolset toggles.
- **[`run_agent.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/model_tools.py), and [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py). The configuration in [`hermes_cli/config.py`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/config.py) resolves this mapping, and [`model_tools.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/model_tools.py), and assign it to the `hermes-cli` toolset in [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/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.