Why Group Tools? Cognitive Load and Blast Radius

+15 Mana ✨
Hermes Toolsets Reference(DOCUMENTATION)

Introduction

Hermes does not give the agent every tool at once. Tools are loaded in named bundles called toolsets. There are two reasons for the grouping: it shrinks the space the model has to think over (cognitive load), and it bounds what the agent can do in a given surface (blast radius). Toolsets are the first lever you reach for when shaping agent behavior.

Key Concepts

  • Toolset: A named bundle of tools that load together. Examples: file, terminal, web, browser, safe.
  • Cognitive load: The number of tools the model has to consider at each turn. More tools mean more confusion and worse selection.
  • Blast radius: The set of things the agent can affect. A toolset without terminal simply cannot run shell commands, no matter what the user asks.

Real World Context

When you run Hermes locally, you probably want everything: files, terminal, web, browser, code execution. When you expose Hermes as a Telegram bot to friends and family, you want much less: maybe web search and image generation, but not terminal access to your machine. Different surfaces, different toolsets. This is not optional polish; it is how Hermes is deployed in real teams.

Deep Dive

Two effects make toolsets worth the design effort:

  1. Smaller toolsets produce better selection. Every tool in the registry costs the model some reasoning to ignore. Loading twenty tools when six would do leads to more wrong picks, especially when descriptions overlap.
  2. Smaller toolsets cap the blast radius. If the terminal tool is not loaded, no clever prompt injection can make the agent run a shell command. The capability simply does not exist in this session.

A toolset is, mechanically, just a name plus a list of tools:

yaml
# Conceptual view
name: web
tools: [web_extract, web_search]

The Hermes registry ships with about two dozen standard toolsets. Some map directly to categories (web, file, terminal, browser). Some are deliberately curated bundles (safe, debugging). Some are platform-specific (hermes-discord, hermes-telegram). The next lesson tours the archetypes.

The key insight: which toolset is active determines what the agent can do. Not the model, not the prompt, not the user. The toolset.

Common Pitfalls

  1. Loading every toolset by default: A common reflex; almost always wrong. It makes the agent slower, less accurate, and more dangerous.
  2. Confusing toolsets with permissions: A toolset is what is loaded. Permissions decide whether a loaded tool can actually run. Both matter; they are not the same.

Best Practices

  1. Start small and add as needed: Begin with the minimum toolset for the surface. Add tools only when a real workflow demands them.
  2. Match toolset to surface: CLI for power users, lighter sets for messaging gateways, very narrow sets for public-facing bots.

Summary

  • Toolsets are named bundles of tools.
  • They reduce cognitive load (fewer tools to choose between) and bound blast radius (fewer capabilities available).
  • The active toolset is the first thing that shapes what an agent can do.
  • Hermes ships with about two dozen standard toolsets covering categories, curated archetypes, and platforms.

Code Examples

yaml
# Selecting toolsets per surface in config.yaml
toolsets:
  - hermes-cli         # default for local CLI
  # - hermes-telegram  # override for Telegram gateway
  # - hermes-discord   # override for Discord gateway

# Or per-session via the CLI flag:
#   hermes chat --toolsets web,file,terminal
✓ Completed