Tools: How Agents Touch the World

+15 Mana ✨
Hermes Tools Overview(DOCUMENTATION)Built-in Tools Reference(DOCUMENTATION)

Introduction

A language model on its own can only produce text. It cannot read your filesystem, search the web, send a message, or run a Python script. Tools are the bridge: they let the model request an action, and they let Hermes execute that action on the model's behalf. Without tools, an agent is a chatbot. With tools, it is an operator.

Hermes ships with a registry of more than seventy built-in tools across seven primary categories, plus any tools you load via MCP or write yourself. Memorizing the registry is the wrong instinct. What matters is understanding the shape of the registry: how it is organized, how the agent picks from it, and where the dangerous edges are.

Key Concepts

  • Tool: A named function the agent can call. Each tool has a name, a description, a JSON schema for arguments, and a runtime implementation.
  • Tool registry: The set of tools currently available in a session. Not every tool is loaded every time. The active set depends on the toolset configuration.
  • Tool call: A structured request from the model, naming the tool and supplying arguments.
  • Tool result: The output Hermes returns to the model after running the tool.

Real World Context

When you ask Hermes to summarize the latest commit on this branch, the model does not know your commit history. What it does know is that there is a tool called terminal whose description mentions running shell commands, and a tool called read_file for reading file contents. So it emits a tool call like terminal({ command: 'git log -1 --stat' }), reads the result, and only then writes a summary. Every interesting Hermes session is structured this way: text out, tool call, tool result, text out.

Deep Dive

A tool in Hermes is defined by four things:

  1. A name, like read_file or web_search. Names are stable identifiers the model uses in tool calls.
  2. A description, a short paragraph telling the model what the tool does and when to reach for it. This is the single most important field for tool selection.
  3. A JSON schema for arguments, so the model knows what fields to fill in and Hermes can validate the call before running it.
  4. An implementation, the actual Python code that runs when the tool is called.

Here is a stripped-down view of how a single turn looks on the wire:

text
User:  read the package.json and tell me the version

Model: (thinking) I should use read_file on package.json.
Model: tool_call read_file { path: 'package.json' }

Hermes: (runs read_file, returns contents)
Hermes: tool_result { content: '{ "name": "my-app", "version": "1.4.2", ... }' }

Model: The version is 1.4.2.

The model does not directly read your disk. It asks Hermes to read your disk, and Hermes either does it or refuses (more on refusal in Section 3.5). This indirection is the entire safety story: tools are the only thing the model can do, and Hermes controls what tools exist.

The registry is large but bounded. As of the current release, the seven primary categories are: Web, Terminal and Files, Browser, Media, Agent Orchestration, Memory and Recall, and Automation and Delivery, plus integrations that connect to external systems (Home Assistant, MCP servers, Spotify, and so on). Section 3.1 lesson 4 walks through what lives in each.

Common Pitfalls

  1. Thinking the model has direct access: Newcomers picture the model reaching into the filesystem. It does not. It can only emit tool calls. Internalizing this changes how you debug: when something fails, you ask which tool was called with which arguments.
  2. Trying to memorize every tool: There are more than seventy. You will not remember them all and you do not need to. Learn the categories and the risk gradient, then let hermes tools list (or the model's own descriptions) handle the rest.

Best Practices

  1. Read tool descriptions before complaining about choices: If the agent picked the wrong tool, the description is usually the reason. Better descriptions produce better choices.
  2. Treat tools as the unit of capability: When planning what an agent can do in a deployment, the question is not what can the model do but which tools does it have access to.

Summary

  • Tools are the bridge between text-producing models and the world they need to touch.
  • A tool is defined by name, description, schema, and implementation.
  • Hermes ships with a registry of more than seventy built-in tools across seven primary categories, plus integrations.
  • Tool calls are indirect: the model asks, Hermes executes. This indirection is the foundation of agent safety.

Code Examples

yaml
# Conceptual view of a tool definition
name: read_file
description: |
  Read a text file from the local filesystem with line numbers
  and pagination. Prefer this over running `cat` in the terminal.
schema:
  path: string  # required, absolute or relative path
  offset: integer  # optional, line to start at
  limit: integer  # optional, max lines to return
✓ Completed