Hermes Agent Ships Tool Search for MCP: 85% Fewer Tool Tokens, 25-Point Accuracy Gain

Every MCP server you connect to Hermes Agent adds tool schemas to the model's context window, every turn, regardless of whether those tools are relevant to the current task. A typical deployment with five MCP servers and 34 tools burns roughly 22,000 tokens per turn on tool definitions alone -- about half of the total per-turn cost.

On May 29, 2026, Hermes shipped a fix. Tool Search is a progressive-disclosure layer that hides MCP and non-core plugin tools behind three bridge tools, serving schemas on demand instead of loading everything upfront. The feature shipped in PR #34493, merged by Teknium, and closes a parallel toolset-scoping security hole found during review.[^1]

The tool schema tax

The numbers are well-documented at this point. Research paper MCP Tools Tax (arXiv 2604.21816) measured 15,000-60,000 tokens per turn for typical multi-server setups.[^2] Anthropic's internal evals recorded tool definitions consuming up to 134,000 tokens before any optimization.

For a concrete Hermes deployment with five MCP servers:

Per-turn cost breakdown (six-turn cache-miss session)

That is two problems, not one. On the cost side, cache-miss sessions start at $0.07-$0.10 per turn just to pay for tool schemas the model may never invoke. On the accuracy side, presenting a model with 30+ irrelevant tool choices causes decision paralysis -- the model spends reasoning budget evaluating options it should not need to consider.

How it works

When Tool Search activates, all MCP and non-core plugin tools are removed from the model's visible tool array and replaced with three bridge tools:

• tool_search(query, limit?) -- searches the deferred tool catalog using BM25
• tool_describe(name) -- loads the full JSON schema for one tool
• tool_call(name, arguments) -- invokes a deferred tool

A typical interaction looks like this:

Model: tool_search("create a github issue")
  -> { matches: [{ name: "mcp_github_create_issue", ... }] }
Model: tool_describe("mcp_github_create_issue")
  -> { parameters: { type: "object", properties: { ... } } }
Model: tool_call("mcp_github_create_issue", { title: "...", body: "..." })
  -> { ok: true, issue_number: 42 }

The three bridge tools cost roughly 300 tokens combined -- a 98% reduction from the 22,000-token schema payload they replace. The tradeoff is one additional round trip for tool_search and one for tool_describe before the actual tool call, but these round trips are cheap: they are short-form LLM turns with minimal output generation.

Retrieval: BM25 with substring fallback

The search layer uses BM25 for its primary retrieval pass, matching the model's natural-language query against a catalog of tool names, descriptions, and parameter names. If BM25 returns zero positive-score hits, a literal substring match on tool names serves as a fallback. This prevents degenerate cases where a search for "github" fails because every tool in a GitHub MCP server contains the word "github" and IDF-based scoring collapses.

The catalog is stateless -- it rebuilds from the current tool-definitions list on every turn. This prevents drift bugs where old tool references persist after a server is removed.

When it activates

Tool Search defaults to auto mode. It activates only when deferrable tool schemas consume at least 10% of the active model's context window. Below that threshold, the tools-array assembly is a pure pass-through with zero overhead.

The decision is re-evaluated every turn. A session with a few MCP tools and a long-context model may never activate. A session with 15+ tools activates. Removing a server mid-session correctly returns tools to direct exposure.

The accuracy numbers

Anthropic ran internal MCP evals comparing model accuracy with and without Tool Search.

Anthropic MCP eval accuracy

Opus 4 saw a 25-point accuracy gain -- from 49% to 74%. Opus 4.5, already a stronger baseline, gained 8.6 points. The improvement comes from removing irrelevant tool schemas, which reduces the model's decision surface and eliminates false-positive tool selections.

Note that ~26 percentage points of accuracy is still retrieval failure on Opus 4. Smaller models perform less reliably on query formulation, which means tool-search quality is partially gated by the model's ability to formulate effective tool_search queries.

Security scoping fix

The PR also closed a critical toolset-scoping bug found during review. In the original implementation, the bridge read its catalog from the global registry -- not the session's granted toolsets. A subagent or kanban worker restricted to mcp-github could tool_search the entire process registry and tool_call any tool, including ones it was never granted.

Before the fix, an E2E test confirmed the leak: a session scoped to enabled_toolsets=['mcp-github'] could tool_call("secret_plugin_danger") and the tool ran. After the fix, the same call was rejected with "not available in this session." The agent's handle_function_call now accepts enabled_toolsets/disabled_toolsets parameters, and both the bridge dispatch and the tool executor enforce the same scope before running any deferred tool.

The _last_resolved_tool_names process-global cache also leaked across sessions before the fix -- growing from 20 to 51 entries after a single search. Post-fix, it stays correctly scoped.

Configuration

Tool Search ships enabled in auto mode and requires no configuration changes for most setups. For explicit control, add to hermes.yaml:

tools:
  tool_search:
    enabled: auto        # auto (default), on, or off
    threshold_pct: 10    # % of context at which auto mode kicks in
    search_default_limit: 5
    max_search_limit: 20

Core Hermes tools (read_file, write_file, terminal, web_search, and the other 40+ built-in tools) are never deferred. Only MCP server tools and non-core plugin tools enter the search layer.

When not to use it

The bridge tools cost roughly 300 tokens plus at least one extra round trip per cold tool. For small toolsets (under 15 tools) or workflows where every tool is used every turn, the overhead of search + describe + call outweighs the schema savings. Tool Search correctly stays inactive in those cases.

There is also no system-prompt cache prefix benefit for the deferred schemas, since they are excluded from the initial prompt assembly entirely. And the auto threshold of 10% is tuned for standard models -- users running 128K+ context models may want to raise threshold_pct to avoid activating on proportionally smaller schema loads.

---

Tool Search is available in Hermes Agent v0.17.0+ (shipped alongside the May 29 merge into main). Update with hermes update and enable MCP servers as usual -- the progressive disclosure activates automatically when the threshold is crossed.

[^1]: Teknium. "feat(tools): progressive tool disclosure for MCP and plugin tools (scoped)." GitHub. May 29, 2026. [^2]: Hamilton et al. "MCP Tools Tax." arXiv:2604.21816. 2026.