A Quiet "Tool Diet": 6 Tool Definitions Slimmed Down, Saving 17%–44% Tokens Per Call

Ever done the math on this: every time you ask Hermes to call a tool, the model has to re-read “what this tool looks like” from scratch — parameters, formats, gotchas, all spelled out in a JSON definition that travels with every request. The longer your session and the more frequent your tool calls, the bigger that fixed overhead grows. Between August 27 and 28, the maintainers merged six PRs doing the same thing: slimming down tools’ JSON definitions. process dropped from 306 to 228 tokens (−25%), todo from 323 to 232 (−28%), read_file from 426 to 244–269, skill_manage from 517 to 427 (−17%), video_generate from ~814 to 458/377, and browser_exec from 803 to 663 (−17%) — with zero change in behavior across all of them.

Why tool definitions are worth trimming

Let’s build an intuitive model first. When Hermes calls a tool, the request must include that tool’s JSON schema: description (what it does), parameters (each parameter’s name, type, constraints), enums, and caveats. That definition travels with every request — it’s not a one-time cost; it’s re-sent on every single turn of your conversation.

If tool A’s definition takes 300 tokens and you call it 50 times in a session, that definition alone burns 15,000 tokens. Hermes ships dozens of built-in tools, and a few heavyweight definitions (like browser_exec’s 800+ tokens) are a “hidden tax” lurking inside every request. This wave targets exactly those tax sources — systematically, under campaign #95681.

The principle: teach every fact exactly once

The core idea across this wave can be summed up in one sentence: delete duplicated teaching, keep the real traps. Broken down:

1. The enum IS the verb list (#97279 process, 306→228, −25%)

process’s description used to re-list all 8 actions (list, kill, submit…) with an explanatory sentence each. Now: self-evident verbs (list, kill) get nothing at all; mechanical ones keep one clause each; the genuinely tricky parts get more emphasis — like the write-vs-submit trap: “submit appends Enter — use it to answer prompts; write sends raw bytes, no newline. On a Windows PTY a lone \n is not a line terminator; the prompt silently never returns.”

2. What the parameter schema already teaches doesn’t get re-taught in prose (#97257 todo, 323→232, −28%)

todo’s description used to spell out the items structure ({id, content, status}) in prose — four lines above the identical JSON schema. The duplicate prose is gone; the schema is the single structural source. The load-bearing rules all survive: enumerate every instance for “all N items” tasks, ONE item in_progress, completed only after verified done (never intent), cancel-and-revise on failure.

3. Capabilities advertised on demand (#97195 read_file, 426→244–269; #97095 video_generate, ~814→458/377)

read_file’s format list is now generated dynamically by capability: whether your install has the anydoc extension decides which formats are advertised; missing formats aren’t advertised at all, and the error message teaches you how to enable them. video_generate goes further: it used to show 10 static params to every session, four of which apologized for themselves (“ignored by providers that do not support it”). Now only the params the active backend actually honors are rendered — negative_prompt, audio, seed, upscale appear only on backends that declare support.

4. Cross-tool dedup (#97152 skill_manage, 517→427, −17%)

skill_manage’s patch machinery uses the same fuzzy-find-and-replace semantics as the patch tool (uniqueness-unless-replace_all, context-for-uniqueness, must-differ) — previously taught twice. Now skill_manage says “same matching semantics as the patch tool” and keeps only the skill-specific facts (empty new_string deletes). It also fixed a real ambiguity: file_path is now explicitly “relative to the skill’s own directory, e.g. ‘references/api.md’ — no leading slash, never absolute.”

5. Numbers speak (#96300 browser_exec, 803→663, −17%)

The earlier browser_exec diet included an A/B verification: the slimmed schema achieved accuracy parity with the original while saving 140 tokens per call.

Why this matters to you

  • Money saved: it’s a fixed per-call cost reduction — the longer your session and the more tool calls, the more you save;
  • More reliable: smaller schemas mean lower comprehension cost for the model and fewer mis-parameterized calls;
  • Zero-friction upgrade: all changes are “zero behavior change,” with contract tests pinning every retained teaching — no “the tool got dumber after upgrading.”

Note: these changes merged on August 27–28 and currently live on upstream main, not yet in a release tag. Once you hermes update to a build containing them, they take effect automatically — nothing to configure.

Further reading