Tools, MCP, and Skills

The Three Layers

Hermes has three distinct systems for extending what the agent can do. They form a layered stack:

Each layer serves a different purpose. Built-in tools are actions the agent can take. MCP tools are external actions the agent discovers at startup. Skills are knowledge the agent reads on-demand to do its job better. They stack: a skill can teach the agent to use MCP tools effectively, and MCP tools work alongside built-in tools in the same conversation.

The Tool Registry

Every built-in tool lives in a single file under tools/ and self-registers at import time into the ToolRegistry singleton. This is the central pattern you must understand:

register() — what goes in

Each tool provides four things when it registers:

registry.register(
    name="terminal",          # unique tool name the LLM calls
    toolset="terminal",        # which toolset it belongs to
    schema={...},              # JSON schema the LLM sees as a function
    handler=lambda args: ...,  # actual implementation — returns JSON string
    check_fn=requirements,        # optional: returns True/False for availability
    requires_env=["API_KEY"],   # optional: env vars needed
)

Availability checks

The check_fn is what makes "system dependency not met" warnings appear in hermes tools list. It's a simple function:

# Some tools are only available on certain platforms
def check_requirements() -> bool:
    return bool(os.getenv("MY_API_KEY"))

# Some need external packages installed
def check():
    try:
        import websockets
        return True
    except ImportError:
        return False

# If check_fn returns False, the tool doesn't appear in the LLM's schema list
# and the model can't call it. No error — it's just invisible.

MCP Servers — External Tool Ecosystems

MCP (Model Context Protocol) connects Hermes to external tool servers — GitHub, filesystem, databases, Supabase, browser automation — as if they were built-in tools. They're discovered at startup and registered into the same ToolRegistry with a mcp_<server>_<tool> prefix.

Server types

Three connection types:

# 1. Stdio — local subprocess (most common)
# Runs as a child process, communicates over stdin/stdout
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "ghp_..."

# 2. HTTP — remote endpoint
# Direct connection to a remote MCP server
mcp_servers:
  my_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."

# 3. HTTP + OAuth — for services like Google Drive, Linear
mcp_servers:
  google_slides:
    url: "https://mcp.example.com/mcp"
    auth: oauth

How MCP tools appear

Once registered, MCP tools look identical to built-in tools from the LLM's perspective. The only difference is the name prefix. For example, with a server called github:

The agent sees all of these alongside terminal, read_file, web_search, etc. It doesn't know which are built-in vs MCP — it just sees a flat list of callable functions.

Progressive Disclosure — For Both Tools AND Skills

Both tools and skills use progressive disclosure, but in different ways:

Tool Search bridge — how tool progressive disclosure works

When the Tool Search bridge is active (default: auto, config at tools.tool_search in config.yaml), MCP and plugin tools are replaced in the model-visible schema by three bridge tools:

# These 3 tools replace ALL deferrable MCP/plugin tools in the API call
tool_search(query, limit)       → Finds deferrable tools by name/keyword, returns catalog
tool_describe(name)              → Returns the full JSON schema for one deferrable tool
tool_call(name, arguments)       → Invokes a deferrable tool with the given arguments

Default mode: auto — if all deferrable tools would consume ≥10% of the context window, they're replaced by the 3 bridge tools. If less than 10%, they pass through unchanged. This means on low-tool-count sessions, you see all tools; on MCP-heavy sessions, the bridge kicks in automatically.

Core tools are NEVER deferred. The 18-28 built-in tools (terminal, file, web, browser, etc.) always ship in the schema. Only MCP and plugin-registered tools can be deferred.

Skills — Procedural Knowledge

Skills are knowledge documents, not executable tools. They always use progressive disclosure — only names + descriptions go in the system prompt, and the agent must explicitly call skill_view() to load full content:

Three access levels

The system prompt only contains the index (Level 0). The agent must explicitly call skill_view() to get details. This is deliberate — 60+ skills at full content would blow the context window.

Skill anatomy

# SKILL.md with YAML frontmatter
---
name: my-skill
description: "Brief description shown in skills_list()"
version: 1.0.0
platforms: [linux, macos]
metadata:
  hermes:
    tags: [python, devops]
    requires_toolsets: [terminal]   # Only shown if terminal is enabled
    fallback_for_toolsets: [web]    # Shown when web tools are unavailable
    config:
      - key: my.setting
        description: "Control setting"
        default: "value"
---

## Procedure
1. Step one with exact commands
2. Step two with pitfalls noted
3. Verification step

Agent-managed skills

This is the self-improvement loop in action. The agent can autonomously create and maintain skills using skill_manage:

# After solving a complex multi-step problem, the agent saves the approach
skill_manage(
    action="create",
    name="deploy-fastapi",
    content="---\nname: deploy-fastapi\n...\n---\n## Steps\n..."
)

# To fix a stale skill mid-use
skill_manage(
    action="patch",
    name="deploy-fastapi",
    old_string="old command",
    new_string="new command",
)

How They Work Together

Key CLI commands reference

Key Takeaways

• Built-in tools self-register via registry.register() — one file, zero core changes
• MCP servers connect at startup and register tools with mcp_<server>_<tool> prefix
• Skills are progressive-disclosure knowledge documents — names in prompt, full content on-demand
• All three layers appear as one flat tool surface to the LLM
• check_fn gates tools — missing deps make tools invisible, not broken
• skill_manage lets the agent create/patch/delete skills — the self-improvement loop