# NousResearch/hermes-agent · Reduce token overhead via lazy/deferred tool loading

## Open now

- 9 issues, 1 PR open on GitHub.
- #13332: Feature: Hybrid Tool Pre-Selection (Semantic + Keyword) — RAG-style schema injection to reduce token overhead without extra LLM round trips
- #34038: RFC: On-demand tool/skill/MCP discovery — decouple schema registration from process lifecycle
- #54963: Shrink the Core: Migrate Non-Essential Tools to Plugins/MCP Servers
- #55139: Shrink the Core: Migrate Non-Essential Tools to Plugins/MCP Servers
- #57044: Core tool schemas are ~15k tokens on every request — add a slim/tiered schema mode
- #60181: \[Feature\]: Let built-in toolsets opt into tool-search deferral (defer_toolsets)
- #60184: feat(tool_search): let built-in toolsets opt into deferral via defer_toolsets
- #63033: \[Feature Request\] /compress should report per-segment token distribution and consider tool schema compression
- #67273: Tool schemas consume 83% of every API request — per-session filtering and lazy loading needed
- PR #35457: feat(tool_search): optional embedding reranker for progressive tool disclosure

These items focus on the high token cost of including all tool schemas in every API request, proposing approaches such as deferred or lazy loading, stub modes, tiered schemas, and opt-in deferral for built-in toolsets. Several also explore RAG-style or semantic tool selection to inject only relevant schemas on demand.

## TL;DR

- 19 member(s): 9 open issue(s), 4 closed issue(s), 1 open PR(s), 1 merged PR(s), 4 PR(s) closed without merging.
- A fix was merged to main in PR #97979. Verify it addresses your case.
- **Recommended:** read PR #97979 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `unresolved`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.08`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #13332: Feature: Hybrid Tool Pre-Selection (Semantic + Keyword) — RAG-style schema injection to reduce token overhead without extra LLM round trips
- #34038: RFC: On-demand tool/skill/MCP discovery — decouple schema registration from process lifecycle
- #54963: Shrink the Core: Migrate Non-Essential Tools to Plugins/MCP Servers
- #55139: Shrink the Core: Migrate Non-Essential Tools to Plugins/MCP Servers
- #57044: Core tool schemas are ~15k tokens on every request — add a slim/tiered schema mode
- #60181: \[Feature\]: Let built-in toolsets opt into tool-search deferral (defer_toolsets)
- #60184: feat(tool_search): let built-in toolsets opt into deferral via defer_toolsets
- #63033: \[Feature Request\] /compress should report per-segment token distribution and consider tool schema compression
- #67273: Tool schemas consume 83% of every API request — per-session filtering and lazy loading needed

## Closed / duplicate issues

- #4379: Token overhead analysis: 73% of each API call is fixed overhead (~13.9K tokens) — data + suggestions
- #6839: Feature: Lazy Tool Schema Loading — Two-Pass Tool Injection to Reduce Token Overhead
- #7961: \[Feature\] Per-profile tool selection — opt-in lightweight toolsets
- #66473: Feature: MCP Smart Loading — Lazy Connection, Tool Budget, Per-Session Scoping & On-Demand Servers

## Prior & competing PRs

- **#97979: feat(tool-search): core-tool deferral — curated event-triggered set behind the bridge (−6.5K tok/call desktop, −49% schemas)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `agent/agent_runtime_helpers.py`, `agent/coding_context.py`, `agent/context_compressor.py`, `agent/conversation_loop.py`, `agent/display.py`, `agent/tool_executor.py`, `agent/tool_guardrails.py`, `agent/turn_summary.py`, `evals/core_tool_deferral/README.md`, `evals/core_tool_deferral/orchestrator.py`, `evals/core_tool_deferral/report.py`, `evals/core_tool_deferral/results/.gitignore`, `evals/core_tool_deferral/results/SUMMARY.md`, `evals/core_tool_deferral/tasks.py`, `evals/core_tool_deferral/worker.py`, `hermes_cli/tools_config.py`, `model_tools.py`, `tests/agent/test_curator.py`, `tests/agent/test_display_todo_progress.py`, `tests/agent/test_phantom_tool_references.py` (+32 more)
- **#35457: feat(tool_search): optional embedding reranker for progressive tool disclosure**. open
  - maintainer direction: category `merged_via`; implication `superseded`; refs `09d86e692`
  - files: `.env.example`, `tests/tools/test_tool_search.py`, `tools/tool_search.py`, `website/docs/user-guide/features/tool-search.md`
- **#43521: feat(tool_search): config-gated builtin tool deferral (#6839)**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `7e310f5037ba`, `#97979`
- **#48622: feat(tools): add stub_mode to reduce main-thread tool schema tokens**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`
- **#60182: feat(tool_search): defer_toolsets — opt built-in toolsets into deferral**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `7e310f5037ba`, `#97979`
- **#61744: feat(tool_search): opt-in deferral for infrequent built-in toolsets**. closed without merge
  - maintainer direction: category `stale_abandoned`; implication `active`

## Fix status

- Merged to main in PR #97979 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-09-02`.
- Subsystem: `agent`