---
title: Hermes Tool Search
type: system
status: active
created: 2026-07-25
updated: 2026-07-25
review_after: 2026-10-23
verified_on: 2026-07-25
version_applies_to: Hermes Agent on CT460
confidence: high
tags: [hermes, automation, system]
sources: [live CT460 configuration and isolated CUA validation]
---

# Hermes Tool Search

## Why it is enabled

Hermes previously sent every external tool schema to the model on every turn.
That used a large part of the context window before the conversation began and
made compaction happen much sooner.

Native Hermes Tool Search is now always on. Core tools remain immediately
available. External tools are discovered only when they are relevant, then
described and called through the Tool Search bridge.

## Active configuration

File: `/home/hermes/.hermes/config.yaml`

```yaml
tools:
  tool_search:
    enabled: "on"
    threshold_pct: 10
    search_default_limit: 5
    max_search_limit: 20
```

`enabled: "on"` is the important setting: it makes Tool Search active on every
request instead of waiting for the tool schemas to cross an automatic token
threshold.

## Verified result

- 80 external tools were deferred in the production gateway.
- Approximately 24,151 schema tokens were removed from the always-present
  prompt.
- 36 core or directly visible tools remained available.
- Estimated fixed baseline fell from about 52,955 to 29,182 tokens, a reduction
  of roughly 45%.
- In an isolated Computer Use test, 53 tools were discovered and the
  `health_report` search, description, and call all succeeded.
- Native Tool Search tests passed: 39 tests.

Tool Search can add a small discovery call when an external tool is first
needed. It should not reduce answer quality: the model retains direct access to
core tools and can search for specialized tools by name or purpose.

## New tools and new skills

New external tools are automatically included in Tool Search after their tool
provider is loaded. They do not need to be manually assigned to a category.

Skills use a separate discovery system:

- `~/.hermes/skills/devops/my-skill/SKILL.md` is categorized as `devops`.
- A skill directly under `~/.hermes/skills/` has no category.
- The skill `name` and `description` come from YAML frontmatter in `SKILL.md`.
- Directory additions are noticed automatically. An in-place edit may take up
  to 30 seconds to appear because of the skill cache.

Tool Search therefore does not decide skill categories. The first directory
below `~/.hermes/skills/` does.

## Rollback

The pre-change configuration is preserved at:

`/home/hermes/.hermes/backups/config.yaml.20260725-before-tool-search`

Restore that file only if Tool Search causes a confirmed regression, validate
the YAML, and restart `hermes-gateway.service`.

## Related

- [[systems/hermes-agent]]
- [[systems/skills-index]]
- [[concepts/tool-calling]]
- [[runbooks/gateway-resource-resilience]]