4 · The Tool System

162 tool files, plus a 39 KB exposure-policy file. This chapter is about how tools are organized, how they are exposed, and how call arguments get coerced.

4.1 The Most Important Design Decision: Implementation Separated from Exposure

The core tool list

# The tool list shared by the CLI and every messaging platform.
# Change it here and every platform is updated at once.
_HERMES_CORE_TOOLS = [
    # web
    "web_search", "web_extract",
    # terminal and process management
    "terminal", "process",
    # Note: desktop-GUI capabilities (read_terminal, open_preview, etc.)
    # are deliberately not listed here, for the same reason as the project tools below:
    # they only make sense where a graphical renderer can respond. They live in the desktop_ui
    # toolset and are enabled solely by the GUI gateway for sessions whose SOURCE is the desktop app —
    # never keyed on a process env var, which is blind to "a desktop client talking to a remote backend."
    # file operations
    "read_file", "write_file", "patch", "search_files",
    # vision and image generation
    "vision_analyze", "image_generate",
    # skills
    "skills_list", "skill_view", "skill_manage",
    # browser automation
    "browser_navigate", "browser_snapshot", "browser_click",
    "browser_type", "browser_scroll", "browser_back",
    "browser_press", "browser_get_images",
    "browser_vision", "browser_console", "browser_cdp", "browser_dialog",
    "browser_exec",          # replaces the other browser tools when browser.backend is "browser-use"
    # text-to-speech
    "text_to_speech",
    # planning and memory
    "todo", "memory",
    # session history search
    "session_search",
    # clarifying questions
    "clarify",
    # code execution and delegation
    "execute_code", "delegate_task",
    # scheduled tasks
    "cronjob",
    # smart home (enabled via check_fn, which looks for HASS_TOKEN)
    "ha_list_entities", "ha_get_state", "ha_list_services", "ha_call_service",
    # kanban multi-agent collaboration — only enters the schema when the agent was spawned
    # as a kanban worker (HERMES_KANBAN_TASK env var set), or the current profile has explicitly
    # enabled the kanban toolset. Controlled via check_fn.
    "kanban_show", "kanban_list", "kanban_complete", "kanban_block",
    "kanban_request_review", "kanban_request_changes", "kanban_heartbeat",
    "kanban_comment", "kanban_create", "kanban_link", "kanban_unblock",
    "kanban_attach", "kanban_attach_url", "kanban_attachments",
    # computer use (macOS; check_fn verifies cua-driver is installed)
    "computer_use",
]

hermes-agent/toolsets.py

The design principles those two comments reveal

Narrowing the trust boundary: the webhook toolset

# Webhook events may originate from untrusted third-party content (for example,
# pull request titles or comments on a public repository). The default webhook toolset is
# deliberately kept narrow so prompt injection can't trigger local file I/O or system command execution.
_HERMES_WEBHOOK_SAFE_TOOLS = [
    "web_search",       # web search (read-only)
    "web_extract",      # extract web page content (read-only)
    "vision_analyze",   # analyze images (read-only)
    "clarify",          # ask the user a question (no side effects)
]

4.2 Composing and Resolving Toolsets

TOOLSETS = {
    "web": {
        "description": "Web research and content extraction tools",
        "tools": ["web_search", "web_extract"],
        "includes": []                          # ★ can include other toolsets
    },
    "search": {
        "description": "Web search only (no content extraction/scraping)",
        "tools": ["web_search"],
        "includes": []
    },
    "vision": { "tools": ["vision_analyze"], ... },
    "video":  { "description": "…(opt-in, not in the default toolsets)",
                "tools": ["video_analyze"], ... },
    "image_gen": { "tools": ["image_generate"], ... },
    ...
}

Each toolset has three fields: a description (for humans), a tool list, and other toolsets it includes.

The resolution functions

def get_toolset(name: str, *, include_registry: bool = True) -> Optional[Dict]
def bundle_non_core_tools(toolset_name: str) -> Set[str]
def resolve_toolset(name: str, visited: Set[str] = None, *,
                    include_registry: bool = True) -> List[str]     # ★ with cycle detection
def resolve_multiple_toolsets(toolset_names: List[str]) -> List[str]
def _get_plugin_toolset_names() -> Set[str]                # toolsets provided by plugins
def _get_registry_toolset_aliases() -> Dict[str, str]      # aliases
def get_all_toolsets() -> Dict[str, Dict[str, Any]]
def get_toolset_names() -> List[str]
def validate_toolset(name: str) -> bool
def create_custom_toolset(...)
def get_toolset_info(name: str) -> Dict[str, Any]

The visited parameter of resolve_toolset is cycle detection: toolset A includes B, B includes A, infinite recursion. A “visited set” prevents it.

The existence of bundle_non_core_tools tells you that the system needs to distinguish “core tools” from “add-on tools” — presumably so they can be treated differently when computing token cost or making exposure decisions.

Toolsets from three sources

The function names show that toolsets come from three places:

• Built-in — hard-coded in the TOOLSETS dictionary
• Plugin-provided — _get_plugin_toolset_names()
• The registry — controlled by the include_registry parameter, with alias support via _get_registry_toolset_aliases()

4.3 Central Tool Dispatch

Hermes has no Tool class abstraction; every tool call goes through the same function:

def handle_function_call(...)      # model_tools.py, line 1240

The registry machinery that goes with it:

TOOL_TO_TOOLSET_MAP:   Dict[str, str]  = registry.get_tool_to_toolset_map()
TOOLSET_REQUIREMENTS:  Dict[str, dict] = registry.get_toolset_requirements()

def get_all_tool_names() -> List[str]
def get_toolset_for_tool(tool_name: str) -> Optional[str]
def get_available_toolsets() -> Dict[str, dict]
def check_toolset_requirements() -> Dict[str, bool]      # ★ dependency check
def check_tool_availability(quiet: bool = False) -> Tuple[List[str], List[dict]]

TOOLSET_REQUIREMENTS is an important mechanism: some tools need external conditions to work.

The comments in the core list say these are “controlled via check_fn” — meaning each tool can supply a check function that decides at runtime whether it is available. Unavailable tools never enter the model's tool list, so they cost no tokens and can't be called only to fail.

4.4 The Argument Coercion Layer

This layer is unique to Hermes, and extremely practical:

def coerce_tool_args(tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]    # line 845
def _schema_accepts_kind(schema: Any, kind: str) -> bool                       # 953
def _normalize_json_strings_for_schema(value: Any, schema: Any) -> Any         # 974
def _coerce_value(value: str, expected_type, schema: dict | None = None)       # 1051
def _schema_allows_null(schema: dict | None) -> bool                           # 1080
def _coerce_json(value: str, expected_python_type: type)                       # 1104
def _coerce_number(value: str, integer_only: bool = False)                     # 1135
def _coerce_boolean(value: str)                                                # 1153
def _canonicalize_tool_call_arguments(arg_str: str) -> str                     # 1293

hermes-agent/model_tools.py

Why this layer is needed

Coercion follows the schema; it is not blind conversion

Look at the signature: _coerce_value(value, expected_type, schema) — it receives the target schema. So coercion has a basis:

• _schema_accepts_kind(schema, kind) — first ask “does this schema accept this kind of value?”
• _schema_allows_null(schema) — “is null allowed?”, which decides whether "null" becomes None
• _normalize_json_strings_for_schema(value, schema) — recursively handle JSON strings inside nested structures, guided by the schema

Blind conversion (say, “every string that looks like a number becomes a number”) would introduce new bugs — a version number "1.20" that should stay a string would become the number 1.2. Deciding by schema avoids that.

4.5 Sanitizing Tool Error Messages

_TOOL_ERROR_ROLE_TAG_RE = re.compile(...)          # strip forged role tags
_TOOL_ERROR_FENCE_OPEN_RE  = re.compile(r'^\s*```(?:json|xml|html|markdown)?\s*',
                                        re.MULTILINE)
_TOOL_ERROR_FENCE_CLOSE_RE = re.compile(r'\s*```\s*$', re.MULTILINE)
_TOOL_ERROR_CDATA_RE = re.compile(r'<!\[CDATA\[.*?\]\]>', re.DOTALL)

def _sanitize_tool_error(error_msg: str) -> str: ...

What attack this defends against

The four regexes each handle one kind of carrier:

4.6 Observing Tool Results, and Hooks

def suppress_post_tool_call_hook()                 # context manager: temporarily disable the hook
def _tool_result_observer_fields(...)
def _emit_post_tool_call_hook(...)

suppress_post_tool_call_hook() is a context manager. Its purpose: certain internal tool calls should not fire the user's hooks.

For example: the agent calls some tool internally in order to do compaction. That isn't part of the user's task, and it shouldn't fire the user-configured “log something after every tool call” hook — otherwise the log drowns in internal operations.

4.7 Recognizing a Delegation Context

def _is_delegated_child_context() -> bool      # am I a delegated subagent?
def _is_dispatcher_owned_worker() -> bool      # am I a worker owned by the dispatcher?
def _get_tool_loop()                           # get the event loop for tool execution
def _get_worker_loop()                         # get the worker's event loop
def _run_async(coro)                           # run a coroutine on the correct event loop

This group of functions deals with a practical problem in Python async programming: subagents may run on different event loops (even different threads). When a tool executes, it has to find the right loop to schedule its coroutine on, or it throws “event loop is closed” or deadlocks.

_is_delegated_child_context() also has a business purpose: a subagent needs to know it is a subagent, so it can apply different behavior (an auto-approval policy, for instance; see Chapter 10).

4.8 Caching Tool Definitions

_TOOL_DEFS_CACHE_MAX = 8
def _clear_tool_defs_cache() -> None
def get_tool_definitions(...)          # line 323, cached
def _compute_tool_definitions(...)     # line 417, the actual computation
def _resolve_active_context_length() -> int

Tool definitions (the list of tools and parameter descriptions sent to the model) are cached, up to 8 copies.

Why multiple copies? Because different situations use different toolsets: one for the main agent, one for subagents, one for kanban workers, one for webhooks… and computing each one means walking every tool, parsing schemas, and checking requirements, which isn't cheap.

The appearance of _resolve_active_context_length() here suggests that generating tool definitions may depend on the size of the context window — presumably trimming some tools or shortening descriptions when the window is small.