Hermes Agent Tool Search: Progressive Disclosure for MCP and Plugin Tools

tools :
  tool_search :
    enabled : auto # auto (default), on, or off
    threshold_pct : 5 # listing budget as a percentage of context
    search_default_limit : 5
    max_search_limit : 20
    listing : auto # embed a grouped name+description catalog manifest
    listing_max_tokens : 20000

tools :
  tool_search : true # equivalent to {enabled: auto}

How It Works

When Tool Search activates for a turn, the model sees three new tools in place of the deferred ones:

tool_search(query, limit?), search the deferred-tool catalog
tool_describe(name), load the full schema for one tool
tool_call(name, arguments), invoke a deferred tool

A typical interaction follows this pattern:

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 }

When the model invokes tool_call, Hermes unwraps the bridge and dispatches the underlying tool exactly as if the model had called it directly. Pre-tool-call hooks, guardrails, approval prompts, and post-tool-call hooks all run against the real tool name, not against tool_call. The activity feed in the CLI and gateway also unwraps so you see the underlying tool, not the bridge.

Tiered Disclosure

Tool Search uses tiered disclosure to manage how much of the catalog is visible to the model. The presence of any deferrable (MCP/plugin) tool activates the bridge; what scales with catalog size is how much of the catalog stays visible, not whether schemas defer.

Tier	Condition	What the model sees
0	No MCP/plugin tools	Every tool eager, no bridge. Pass-through.
1	Deferred catalog's listing fits the budget	Bridge + a skills-style manifest of every deferred tool (name + short description, degrading to names-only when over budget). Degradation is per server: when one oversized server (e.g., Cloudflare) is attached alongside small ones (e.g., Linear), the small servers keep their per-tool listings and only the oversized server collapses to a summary line.
2	Per-tool listing exceeds the budget even names-only for every server (e.g., Cloudflare's flat API surface alone: ~3,300 tools whose names are ~32K tokens)	Bare bridge + a one-line-per-server summary (server name + tool count), so the model knows which domains are reachable; individual tools are discoverable only through tool_search.

The listing budget is calculated as min(threshold_pct% of context, listing_max_tokens). The decision is re-evaluated every time the tools array is built, so adding or removing MCP servers mid-session moves the session between tiers on the next assembly.

Implementation Details

• Retrieval uses BM25 over tokenized tool name, description, and parameter names. It falls back to a literal substring match on the tool name when BM25 returns no positive-score hits, which protects against zero-IDF degenerate cases (e.g., searching for "github" against a catalog where every tool name contains "github").
• The catalog is stateless across turns. It rebuilds from the current tool-defs list every assembly, with no session-keyed Map. This avoids the class of bug where a stored catalog drifts out of sync with the live tool registry.
• The catalog is scoped to the session's toolsets. tool_search, tool_describe, and tool_call only ever see and invoke tools the session was actually granted. A subagent, kanban worker, or gateway session restricted to a subset of toolsets cannot use the bridge to discover or call a tool outside that subset. The deferred catalog is the deferrable slice of the session's own enabled/disabled toolsets, not the whole process registry.
• Hermes uses the simpler "structured tools" mode (search/describe/call as plain functions). There is no JS sandbox; the JS-sandbox "code mode" that some other implementations offer is a large surface area that Hermes skips.

Requirements and Limitations

Tool Search has the following requirements and limitations, as documented in the official source:

• Built-in Hermes core tools (terminal, read_file, write_file, patch, search_files, todo, memory, browser_*, web_search, web_extract, clarify, execute_code, delegate_task, session_search, and the rest of _HERMES_CORE_TOOLS) are always loaded directly and are never deferred. Only MCP tools and non-core plugin tools are eligible for deferral.
• Tool Search trades a fixed per-turn token cost (the three bridge tool schemas plus the catalog listing) and at least one extra round trip on cold tools (describe → call) for the savings on the deferred schemas. At tier 1, the listing keeps every capability visible, so the discovery round trip usually disappears, the model goes straight to tool_describe. Live benchmarking showed the listing mode matching eager loading's task success while costing less than the bare bridge.
• If you want the old always-eager behavior for a small toolset, set enabled: off.
• One extra round trip on cold tools: the first time the model needs a deferred tool, it spends one or two extra model calls to find and load the schema. The token savings on the static side are real, but a portion is paid back at runtime.
• No cache benefit on deferred schemas: a loaded tool_describe result enters the conversation history (so it does get cached on subsequent turns) but it never benefits from the system-prompt cache prefix.
• Model-quality dependence: Tool Search assumes the model can write a reasonable search query for the tool it wants. Smaller models do this less well. The published Anthropic numbers (49% to 74% on Opus 4 with vs. without tool search) show the upside but also that approximately 26 points of accuracy is still retrieval failure.
• Toolset edits invalidate cache: adding or removing a tool mid-session changes the bridge tools' descriptions (which include the count of deferred tools) and the catalog, so the prompt cache is invalidated. This is the same trade-off as any toolset edit.
• The threshold_pct range is 0, 100. The max_search_limit range is 1, 50. The listing_max_tokens range is 200, 60000.

Troubleshooting

The official documentation does not provide specific troubleshooting steps for Tool Search. However, based on the documented behavior, the following considerations may help:

• If the model is not finding tools via tool_search, check that the tools are actually deferrable (MCP or non-core plugin tools) and that enabled is not set to off. Built-in Hermes core tools are never deferred and will not appear in the catalog.
• If the model is not using tool_search at all, consider enabling the listing (listing: auto or listing: on) so the model can see tool names and descriptions directly, reducing the need for search.
• If the catalog seems incomplete, verify that the session has been granted access to the relevant toolsets. The catalog is scoped to the session's toolsets, so a restricted session will not see tools outside its grant.
• If performance is poor with a very large catalog (e.g., Cloudflare's ~3,300 tools), the tier-2 behavior (bare bridge + server summary) will activate automatically. The model will need to rely on tool_search to find individual tools. Adjusting listing_max_tokens may help fit more of the listing into the budget.
• If the model is making excessive round trips, check whether the listing is being embedded. At tier 1, the listing should allow the model to skip tool_search and go directly to tool_describe. If the listing is not fitting, consider increasing threshold_pct or listing_max_tokens.