hermes-tool-context-usage

A tiny tool for Hermes Agent that shows how many tokens each tool's schema costs in your context window — per tool and grouped per toolset — so you can decide what to keep and what to disable.

Useful if you run Hermes against a small local model and your context fills up before you've done anything. Every enabled tool's full JSON schema is sent on every request; this tells you exactly where that budget goes.

Why build this?

I am interested in running Hermes with local models and read some reports on Reddit regarding context bloat on Heremes with people reporting having the 64k context almost full with a simple "hello" message.

I am a fan of turning everything that comes by default off and turning on why I need (or think is worth it), so I build this tool to get more awareness of the tools footprint and help me to decide what to leave on.

What it does

• Resolves the same enabled toolsets your live session uses (honoring your platform_toolsets config), so the numbers match what's actually on the wire. This is more accurate than hermes prompt-size, which counts all toolsets and overcounts if you've trimmed.
• Measures each tool individually — total tokens, plus the description-vs-parameters split.
• Rolls the totals up by toolset (the unit you toggle with hermes tools).
• Flags which tools are core (always loaded) vs MCP/plugin (lazy loaded).

No network calls are made. All local.

Requirements

• Hermes Agent installed and working (the hermes command runs).
• That's it — the script runs under Hermes' own Python, so its dependencies are already present.

Run it

Option A — the launcher (easiest)

The shell script finds the Python that Hermes is installed under and runs the analysis for you:

git clone https://github.com/aguyintech/hermes-tool-context-usage.git
cd hermes-tool-budget
./hermes_tool_context_usage.sh

Flags pass straight through:

./hermes_tool_context_usage.sh --all-tools          # measure ALL toolsets (worst case)
./hermes_tool_context_usage.sh --platform telegram  # simulate another platform's toolset
./hermes_tool_context_usage.sh --json               # machine-readable output

Option B — run the Python directly

If you'd rather skip the launcher, point your shell at the Hermes Python yourself. This one-liner pulls the interpreter path out of the hermes launcher:

HERMES_PY=$(grep -v '^#' "$(command -v hermes)" | grep -oE '/[^" ]+/bin/' | head -1)python
"$HERMES_PY" hermes_tool_context_usage.py
"$HERMES_PY" hermes_tool_context_usage.py --all-tools

echo "$HERMES_PY" should print something inside Hermes' venv, e.g. ~/.hermes/hermes-agent/venv/bin/python.

The one-liner assumes the standard installer's launcher (a bash wrapper that exec's into the venv). If you installed via pip/pipx and it comes up empty, run cat "$(command -v hermes)" and use the venv bin/python path you see there. hermes_tool_context_usage.py also has a built-in fallback that tries to locate the interpreter on its own, so plain python3 hermes_tool_context_usage.py often works too.

Reading the output

Tool-schema budget · platform=cli · ceiling (all credentialed toolsets — like prompt-size)
tokenizer: chars/4 approx · tool_search: enabled=auto, threshold_pct=10.0
29 tools · 11,959 tokens
  of which deferrable (MCP/plugin): 188 tokens — the rest are core, never deferred

By toolset (the unit you toggle with `hermes tools`):
  toolset                tools    tokens      %
  delegation                 1     1,925  16.1%
  terminal                   2     1,711  14.3%
  browser                   10     1,552  13.0%
  file                       4     1,475  12.3%
  skills                     3     1,335  11.2%
  session_search             1     1,249  10.4%
  code_execution             1       600   5.0%
  memory                     1       545   4.6%
  todo                       1       343   2.9%
  clarify                    1       320   2.7%
  image_gen                  1       247   2.1%
  tts                        1       238   2.0%
  vision                     1       231   1.9%
  video                      1       188   1.6%

Top tools by token cost  (D = deferrable behind tool_search):
  tool                      toolset            D   tokens  (desc/params tok)
  delegate_task             delegation         ·    1,925  (776/1,118)
  terminal                  terminal           ·    1,393  (581/783)
  session_search            session_search     ·    1,249  (675/536)
  skill_manage              skills             ·    1,025  (447/552)
  execute_code              code_execution     ·      600  (508/56)
  memory                    memory             ·      545  (381/137)
  patch                     file               ·      482  (121/339)
  search_files              file               ·      446  (109/313)
  todo                      todo               ·      343  (162/158)
  clarify                   clarify            ·      320  (194/102)
  process                   terminal           ·      318  (90/206)
  browser_vision            browser            ·      299  (164/111)
  write_file                file               ·      286  (97/167)
  read_file                 file               ·      261  (130/109)
  browser_console           browser            ·      252  (116/112)
  image_generate            image_gen          ·      247  (120/104)
  text_to_speech            tts                ·      238  (99/115)
  skill_view                skills             ·      233  (90/120)
  vision_analyze            vision             ·      231  (117/91)
  browser_navigate          browser            ·      213  (150/39)
  browser_snapshot          browser            ·      205  (128/53)
  video_analyze             video              D      188  (80/86)
  browser_type              browser            ·      126  (43/60)
  browser_click             browser            ·      117  (53/41)
  browser_scroll            browser            ·      103  (40/39)
  browser_press             browser            ·      100  (37/40)
  browser_get_images        browser            ·       79  (45/9)
  skills_list               skills             ·       77  (22/32)
  browser_back              browser            ·       58  (25/9)

This is the --all-tools run (every credentialed toolset enabled). Your real session — only the toolsets you've actually kept — will be a subset of this.

• Core tools can't be deferred. Your only lever for them is not enabling them.
• Trim your tools. Use this information to disable tools or entire toolsets, eith using the Hermes Cli or the Hermes Desktop (easier on the UI).
• MCP/plugin tools (marked D) are lazy-loaded via Tool Search once they cross a context threshold, so they're cheaper to keep around.
• Skills don't appear here. Hermes loads skills on demand (progressive disclosure); only a tiny one-line index sits in the prompt, so installing skills barely costs context. Don't disable skills to save tokens — it's the wrong lever.

A note on token counts

Counts use the chars/4 rule, the same estimate Hermes uses internally for its Tool Search threshold. Install tiktoken into the Hermes venv and the script will use the cl100k encoder instead. Neither is exact for non-OpenAI local models, but both are more than good enough to rank tools and make keep/cut decisions.

License

MIT