Hermes Tool Router is an experimental plugin for the Hermes agent that shrinks the tool schema sent on the first turn of a conversation. It classifies only that first turn: when the classification is confident, a smaller tool surface goes to the main model; when it is uncertain, the full catalog is sent instead. Later turns reuse the surface chosen at the start rather than reclassifying, and if a pruned tool is needed the owning toolset is added permanently for the session.
Routing runs through stock Hermes extension points, so no change to Hermes itself is required. First-turn savings come from either an early surface hook or the pre_llm_call compatibility path, which runs before the provider request is assembled; a bundled diagnostics.py reports whether a routing path is available before that request and exits with code 2 when the current runtime cannot claim first-turn savings.
Classification is deterministic by default and needs no API key. An optional model classifier can be enabled for ambiguous requests, configured with a provider, model, confidence threshold, and hard timeout; a local OpenAI-compatible endpoint can be used instead of a hosted one. Every failure mode — timeout, malformed output, missing confidence, registry mismatch, or unsupported runtime — falls back to the complete tool surface.
Against a live 39-tool Hermes registry, the project reports these first-request schema-token measurements from Hermes’s own estimator, alongside a paired live evaluation using openai/gpt-5.4-mini that recorded 10 of 10 safe-core cases passed, 100% required-toolset recall and route accuracy, and a 61.60% average reduction in actual first-provider-request tokens:
| Routed toolsets | Baseline tokens | Routed tokens | Reduction |
|---|---|---|---|
| web | 18,627 | 490 | 97.37% |
| file,terminal | 18,627 | 3,207 | 82.78% |
| browser,web | 18,627 | 3,364 | 81.94% |
Features
- First-turn routing: intent classification narrows the live tool surface before the first provider request
- Session-sticky surface: later turns reuse the initial surface instead of reclassifying and shrinking it
- Monotonic recovery: requested toolsets are added permanently for the session and never pruned again
- Fail open: uncertainty, invalid classifier output, timeouts, or an unsupported runtime keep the full tool surface
- Optional classifier: model-driven routing is off by default and gated by a confidence threshold and hard timeout
- Local endpoint support: a custom OpenAI-compatible base URL can serve the classifier instead of a hosted provider
- Automatic tool recovery: generic tool_request middleware expands a pruned tool’s owning toolset before validation and dispatch
- Plugin-only install: runs on stock Hermes extension points with no core patch
- Diagnostics command: reports whether a routing path exists before the provider request, with a distinct exit code when it does not
- Host-admission contract: protected tool definitions stay bounded by the host-admitted envelope, and invalid policy denies additions rather than broadening
- Onboarding skill: a first-run skill explains the router, offers the optional classifier key once, and walks through verification
