Activation and Configuration

Activating Tool Search

1. Set tools.tool_search.enabled to 'auto' (default) or 'on' to activate when at least one deferrable tool exists.
2. Optionally configure threshold_pct, search_default_limit, max_search_limit, listing, and listing_max_tokens.
3. Alternatively, set tools.tool_search to true (equivalent to {enabled: auto}).
4. To disable entirely (everything stays eager), set enabled: off.

Parameters

Parameter	Meaning	Required	Default
tools.tool_search.enabled	Controls activation: 'auto' (default) or 'on' activate whenever at least one deferrable tool exists; 'off' disables entirely (everything stays eager).	No	'auto'
tools.tool_search.threshold_pct	Listing budget as a percentage of the active model's context length. Range 0–100.	No	5
tools.tool_search.search_default_limit	Hits returned when model calls tool_search without a limit.	No	5
tools.tool_search.max_search_limit	Hard upper bound the model can request via limit. Range 1–50.	No	20
tools.tool_search.listing	Controls embedding of skills-style manifest of every deferred tool (name plus first sentence of description, ≤60 chars, grouped by MCP server) in tool_search bridge description. 'auto' includes when it fits budget (falling back to names-only, then tier-2 server summary); 'on'/'off' force either way.	No	'auto'
tools.tool_search.listing_max_tokens	Absolute cap on embedded listing, regardless of context size. Range 200–60000.	No	20000

Typical Interaction Flow

1. The model calls tool_search with a query to find relevant deferred tools.
2. The model receives matches with tool names and descriptions.
3. The model calls tool_describe with the exact tool name to load its full schema.
4. The model calls tool_call with the tool name and arguments to invoke the underlying tool.
5. Hermes unwraps the bridge and dispatches the real tool; hooks and activity feed see the real tool name.

Example

The model calls tool_search('create a github issue') and receives matches with tool names and descriptions. The model then calls tool_describe('mcp_github_create_issue') and receives the full parameter schema. Finally, the model calls tool_call('mcp_github_create_issue', { title: '...', body: '...' }) and receives { ok: true, issue_number: 42 }.

Constraints and Caveats

• Built-in Hermes core tools are never deferred; only MCP tools and non-core plugin tools are eligible.
• 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.
• No cache benefit on deferred schemas: a loaded tool_describe result enters conversation history (cached on subsequent turns) but never benefits from the system-prompt cache prefix.
• Model-quality dependence: the bridge assumes the model can write a reasonable search query for the desired tool; smaller models do this less well.
• Toolset edits invalidate cache: adding or removing a tool mid-session changes the bridge tool descriptions (including the count of deferred tools) and the catalog, invalidating the prompt cache.
• The catalog is scoped to the session's toolsets; a subagent, kanban worker, or gateway session restricted to a subset of toolsets cannot use the bridge to discover or call tools outside that subset.
• No JS sandbox; the bridge uses plain functions for search, describe, and call.

Failure Modes

Without a listing, deferred capabilities are invisible. Models may substitute visible core tools (for example, running gh in the terminal instead of searching for a deferred GitHub tool) or declare a capability nonexistent instead of calling tool_search.

Published Anthropic numbers show a 49% to 74% improvement on Opus 4 with tool search versus without it. However, approximately 26 points of accuracy still represent retrieval failure.

BM25 may return zero positive-score hits for degenerate cases (for example, searching 'github' against a catalog where every tool name contains 'github'). In such cases, the system falls back to literal substring match on the tool name.

The catalog is stateless across turns to avoid drift, but it rebuilds from the current tool-defs list every assembly.

Prerequisites

• At least one MCP server or non-core plugin tool must be attached to the session.
• The model must be capable of writing reasonable search queries for the tools it wants.
• You must accept the token savings versus extra round trip trade-off.

Performance Considerations

The bridge is designed to save tokens. For example, with a context window of 3300 tokens, the listing budget would be 5% of that, or 165 tokens, which is far below the listing_max_tokens default of 20000. This means the bridge would likely operate in Tier 2, showing only a server summary, and individual tools would be discoverable only via tool_search. This demonstrates how the bridge adapts to limited context budgets.

The bridge re-evaluates the tier every time the tools array is built, so mid-session changes to MCP servers can move the session between tiers on the next assembly. This ensures the bridge always operates within the available budget.