toolgz 0.2.10 → 0.2.11

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong>Your agent spends 30–70k tokens of context on tool definitions before the user types a word. toolgz gets up to ~85% of it back.</strong></p>
 
-<p><em>On a large tool set, at level 3. The default (level 1) reclaims 13–39% and gives up nothing. <code>recommendLevel()</code> tells you which one your tools want; you pass its answer in.</em></p>
+<p><em>On a large tool set, at level 3. The default (level 1) reclaims 13–39% on real-world tool definitions and gives up nothing. <code>recommendLevel()</code> tells you which one your tools want; you pass its answer in.</em></p>
 
 <p>
 <a href="#measured-results">420-run cross-provider sweep</a> ·
@@ -44,7 +44,7 @@ Reclaiming the room is what this does.
 ```ts
 import { compress, recommendLevel, forAnthropic } from "toolgz";
 
-const { level } = recommendLevel(myTools);    // advice: 1 for a small block, 3 for a big one
+const { level } = recommendLevel(myTools);    // advice: 0, 1 or 3 — see below
 const c = compress(myTools, { level });       // your existing MCP/SDK tool array
 const { tools, system } = forAnthropic(c);    // send these instead
 ```
@@ -54,6 +54,11 @@ provider schema enforcement intact, and 13–39% smaller (13–32% on the synthe
 **level 3**, which is what `recommendLevel` returns once a tool set is big enough to
 amortise the dispatcher.
 
+Level 1 earns that by stripping prose, so it needs prose to strip: if your descriptions
+are already one short sentence, it **adds** ~15% instead and `recommendLevel` returns
+**0** — leave the tools alone. Real MCP catalogues are verbose, which is why they land at
+the top of that range.
+
 **Note the shape of those three lines: `recommendLevel` only advises, and you pass its
 answer back in.** Nothing upgrades itself — `compress(myTools)` is level 1 whether you
 have 2 tools or 500. See [Which level to use](#which-level-to-use) for why.
@@ -78,8 +83,10 @@ committed in [`bench/results/`](bench/results/); recompute any figure with
 
 **The table below uses a synthetic catalogue** — 100 realistic-but-invented MCP-style
 tools across 9 namespaces — because it lets us build deliberately confusable clusters
-that a real catalogue may not contain. Two things follow from that, and the first is
-uncomfortable:
+that a real catalogue may not contain. Four of the five scenarios draw a 30-tool
+confusable subset from it; the fifth (`acc-haystack`) uses all 100.
+
+Two things follow from that, and the first is uncomfortable:
 
 - Synthetic naming can flatter a compression style. One map style measured −21% on
   this fixture because every tool name carried a `namespace_op` prefix to factor out.
@@ -206,7 +213,7 @@ the tool name that compression takes away.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/img/reliability-dark.svg">
-  <img src="docs/img/reliability-light.svg" alt="Task completion by level-3 map style and provider, showing bare names failing on grok-4.5">
+  <img src="docs/img/reliability-light.svg" alt="Task completion by level-3 map style and provider. Bare names fail on grok-4.5; that style and the terse-description style were removed in 0.2.0 and are marked as such">
 </picture>
 
 The model doesn't lose the ability to choose — it converts a recall problem into a retrieval
@@ -214,6 +221,10 @@ problem and looks up what it needs. The default map style exists because of the
 bare tool names failed on `grok-4.5` **deterministically**, 3 of 3 attempts on one scenario,
 answering with zero tool calls and no error raised. Naming the required arguments fixed it.
 
+Two of the four rows are marked **(removed)**: those styles were deleted in 0.2.0 and you
+cannot select them. They are charted anyway because they *are* the evidence for the
+default — deleting the losing arms would delete the reason.
+
 ### How we found the cost story, and got it wrong twice
 
 <picture>
@@ -243,6 +254,11 @@ tried and removed in 0.2.0 because they were smaller and still worse.
 
 ### The whole idea, in plain English
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/metaphor-dark.svg">
+  <img src="docs/img/metaphor-light.svg" alt="Three panels. Level 0: the full menu, 149 tools on the wire, nothing saved, kitchen checks the order. Level 1: the same menu with prose cut, 149 tools on the wire, 45.2% smaller, kitchen still checks the order. Level 3: a small numbered card and one waiter, 2 tools on the wire, 96.5% smaller, toolgz checks the order instead of the provider.">
+</picture>
+
 Your tool definitions are a **menu** handed to the model at the start of every single
 conversation. It is long, and most of it is flowery prose about each dish.
 
@@ -267,7 +283,7 @@ So: **level 1 is smaller. Level 3 is much smaller and you take over order-checki
 compress(myTools)                    // level 1. ALWAYS — 2 tools or 500.
 compress(myTools, { level: 3 })      // level 3, because you asked for it
 
-const { level } = recommendLevel(myTools);   // just advice: returns 1 or 3
+const { level } = recommendLevel(myTools);   // just advice: returns 0, 1 or 3
 compress(myTools, { level });                // now it's 3, because you passed it in
 ```
 
@@ -297,7 +313,7 @@ saving.
 
 ### The levels in full
 
-Ask the library. It returns 1 or 3, never 2, and explains itself:
+Ask the library. It returns 0, 1 or 3 — never 2 — and explains itself:
 
 ```ts
 import { recommendLevel } from "toolgz";
@@ -964,13 +980,21 @@ Returns:
 > Use it as a local signal. For anything you publish, measure with your provider's token
 > counter. `originalChars` and `compressedChars` are on `stats` for the raw counts.
 >
-> A negative value is possible and correct: on a very small tool set, level 1's signature
-> line can exceed the per-property descriptions it strips.
+> A negative value is possible and correct. Level 1 pays for a signature line and gets
+> paid by the prose it strips, so on tools whose descriptions are already terse it comes
+> out **~15% larger** — `recommendLevel` returns 0 in that case rather than recommending
+> it. Even level 0 reports **−0.6%**: `c.tools` is Anthropic-shaped, and `input_schema` is
+> one character longer than the `inputSchema` most callers pass in. Structural, not waste.
 | `encodeCallForTest(name, args)` | `→ {name, args}` | build the raw call a model would emit; test aid |
 
 ### `recommendLevel(tools, namespaceOf?) → Recommendation`
 
-`{ level, reason, toolCount, namespaceCount, opsPerNamespace }`. Returns 1 or 3, never 2.
+`{ level, reason, toolCount, namespaceCount, opsPerNamespace }`. Returns 0, 1 or 3, never 2.
+
+**`level: 0` means this library has nothing to offer your tool set.** Level 1 would
+inflate it — terse descriptions leave no prose to strip, so the signature line is pure
+addition — and the block is too small for level 3's trade to be worth it. Telling you that
+is more useful than recommending a transform that makes the payload bigger.
 
 **It advises; it does not act.** Pass the answer back in yourself —
 `compress(tools, { level })`. Calling `compress(tools)` alone is level 1 regardless of

package/dist/recommend.d.ts

@@ -44,6 +44,11 @@ export type Recommendation = {
  * there unless the caller passes a level explicitly — level 3 trades away the
  * provider's own schema enforcement, and that is not a trade to make on a
  * caller's behalf because their tool array grew.
+ *
+ * Returns 0, 1 or 3 — never 2. **0 means "this library has nothing to offer
+ * here"**: level 1 would inflate the block, and it is too small for level 3's
+ * trade to be worth it. Saying so is more useful than recommending a transform
+ * that makes the payload bigger.
  */
 export declare function recommendLevel(tools: Tool[], namespaceOf?: (n: string) => {
     ns: string;

package/dist/recommend.js

@@ -38,6 +38,11 @@ import { compress } from "./index.js";
  * there unless the caller passes a level explicitly — level 3 trades away the
  * provider's own schema enforcement, and that is not a trade to make on a
  * caller's behalf because their tool array grew.
+ *
+ * Returns 0, 1 or 3 — never 2. **0 means "this library has nothing to offer
+ * here"**: level 1 would inflate the block, and it is too small for level 3's
+ * trade to be worth it. Saying so is more useful than recommending a transform
+ * that makes the payload bigger.
  */
 export function recommendLevel(tools, namespaceOf = defaultNamespaceOf) {
     const namespaces = new Set(tools.map((t) => namespaceOf(t.name).ns));
@@ -53,7 +58,8 @@ export function recommendLevel(tools, namespaceOf = defaultNamespaceOf) {
     // real MCP tools the ratio is a stable ~2.1 chars/token (1.98 at 10 tools, 2.15 at
     // 149), so dividing gives a fair local estimate with no API call.
     const CHARS_PER_TOKEN = 2.1;
-    const l1Tokens = Math.round(compress(tools, { level: 1 }).stats.compressedChars / CHARS_PER_TOKEN);
+    const l1 = compress(tools, { level: 1 });
+    const l1Tokens = Math.round(l1.stats.compressedChars / CHARS_PER_TOKEN);
     // The old heuristic gated level 3 on `opsPerNamespace >= 4`. That is a LEVEL-2
     // question: level 2 pays dispatcher overhead per namespace, so its shape matters
     // there. Level 3 uses one flat dispatcher and does not care about namespaces at all.
@@ -73,10 +79,30 @@ export function recommendLevel(tools, namespaceOf = defaultNamespaceOf) {
     // 4,000 threshold for pushing 14-tool sets into dispatcher mode; they were right.
     const THRESHOLD_TOKENS = 10000;
     if (l1Tokens < THRESHOLD_TOKENS) {
+        // Level 1 is not unconditionally free, and this function used to assume it was.
+        //
+        // Level 1 saves by truncating each description to its first sentence and stripping
+        // per-property prose from the schema, and it spends by prepending a signature line.
+        // On a real MCP catalogue the prose dominates and it nets ~45%. On tools whose
+        // descriptions are already one short sentence there is nothing to strip, the
+        // signature is pure addition, and level 1 comes out ~15% LARGER than doing nothing.
+        //
+        // Reported by an external reviewer at 25-1,000 generated tools; they read it as
+        // correct behaviour for level 1, which it is. What is not correct is *recommending*
+        // it: a recommendation that inflates the payload is worse than no recommendation.
+        // So say so, and name level 3 as the real alternative rather than implying the
+        // choice is between level 1 and nothing.
+        if (l1.stats.savedPct <= 0) {
+            return {
+                ...base,
+                level: 0,
+                reason: `Level 1 would make this block ${Math.abs(l1.stats.savedPct).toFixed(1)}% LARGER, not smaller — your descriptions are already terse, so there is no prose to strip and level 1's signature line is pure overhead. Leave the tools alone. If you want the room anyway, level 3 does compress this (${compress(tools, { level: 3 }).stats.savedPct.toFixed(1)}%), at the cost of the provider's own argument validation; at ~${l1Tokens.toLocaleString()} tokens that trade is usually not worth it.`,
+            };
+        }
         return {
             ...base,
             level: 1,
-            reason: `The tool block is only ~${l1Tokens.toLocaleString()} tokens at level 1. Level 3 would be smaller, but not by enough to be worth giving up the provider's own argument validation, which level 1 keeps. Reach for level 3 when the block is large enough that reclaiming it changes what fits in your context.`,
+            reason: `The tool block is only ~${l1Tokens.toLocaleString()} tokens at level 1, which saves ${l1.stats.savedPct.toFixed(1)}%. Level 3 would be smaller, but not by enough to be worth giving up the provider's own argument validation, which level 1 keeps. Reach for level 3 when the block is large enough that reclaiming it changes what fits in your context.`,
         };
     }
     return {

package/llms.txt

@@ -75,12 +75,18 @@ before toolgz existed.
 
 ## Choosing a level
 
-Ask, don't guess: `recommendLevel(myTools)` returns `{ level, reason }` — 1 or 3, never 2.
+Ask, don't guess: `recommendLevel(myTools)` returns `{ level, reason }` — **0, 1 or 3**,
+never 2.
+
+`level: 0` means *leave the tools alone*: level 1 would make this block larger, and it is
+too small for level 3 to be worth giving up provider-side validation. Level 1 is not
+unconditionally free — it saves by stripping prose, so on tools whose descriptions are
+already one short sentence it adds ~15% instead. Do not override a 0 without measuring.
 
 | Level | Wire | Names | Provider schema enforcement | When |
 |:-:|---|:-:|:-:|---|
 | 0 | unchanged | real | yes | A/B control only |
-| **1** | one native tool each, flattened schemas | real | **yes** | **default.** Reclaims 13–39%, gives up nothing |
+| **1** | one native tool each, flattened schemas | real | **yes** | **default.** Reclaims 13–39% on verbose real-world schemas; **inflates ~15% on already-terse ones** |
 | 2 | one tool per namespace | real | no | only if you need real op names on the wire |
 | **3** | one dispatcher + one lookup | codes | no | **large tool sets.** Up to ~85–96% |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolgz",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Compress LLM tool definitions to reclaim context window. Measured across Anthropic, OpenAI, Google and xAI.",
   "main": "dist/index.js",
   "scripts": {
@@ -12,7 +12,8 @@
     "test:live": "vitest run tests/integration",
     "bench:tier1": "tsx -r dotenv/config bench/harness/run-multi.ts --provider=all --suite=real --variants --reps=1 --scenario=real-daily-vs-weekly,real-overwrite-vs-append,real-status-vs-result,real-rollup-vs-detail",
     "bench:tier2": "tsx -r dotenv/config bench/harness/run-multi.ts --provider=all --suite=real --variants --reps=2 --scenario=real-daily-vs-weekly,real-overwrite-vs-append,real-status-vs-result,real-rollup-vs-detail,real-two-step-scheduling,real-summary-vs-details",
-    "bench:tier3": "tsx -r dotenv/config bench/harness/run-multi.ts --provider=all --suite=real --variants --reps=3"
+    "bench:tier3": "tsx -r dotenv/config bench/harness/run-multi.ts --provider=all --suite=real --variants --reps=3",
+    "img:metaphor": "tsx bench/metaphor.ts"
   },
   "keywords": [
     "llm",