toolgz 0.2.10 → 0.2.12

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";
@@ -422,6 +438,35 @@ style in 0.2.0.
 
 ---
 
+## See it run
+
+A demo you can put on a screen. It prints every step — the tool definitions going in,
+what `compress()` turns them into, the request, the model's actual response, the
+`resolve()` translation, and your dispatcher running unchanged.
+
+```bash
+npm run demo -- --level=3          # one level, every step
+npm run demo -- --compare          # levels 0, 1 and 3 back to back
+npm run demo -- --level=3 --offline   # no API key: scripted model, real library
+```
+
+`--compare` ends with the side-by-side:
+
+```
+  level  wire tools  definition chars  reclaimed  turns  argument checking
+  0      6 → 6       3,283 → 3,289     -0.2%      2      provider
+  1      6 → 6       3,283 → 1,999     39.1%      2      provider
+  3      6 → 2       3,283 → 807       75.4%      2      toolgz
+```
+
+It really runs the loop against a real model unless you pass `--offline`, and it says
+which it did. Level 3 also demonstrates the two outcomes a happy path never shows —
+a bad code coming back `kind: "error"` and recoverable, and a `q()` lookup coming back
+`kind: "meta"` with nothing dispatched.
+
+Not shipped in the npm package: it imports a provider SDK, which is a devDependency,
+and the library's zero-runtime-dependency guarantee is not negotiable.
+
 ## Runnable examples
 
 Five files in [`examples/`](examples), all offline — no API key, no cost. Every one is
@@ -935,11 +980,37 @@ number can be recomputed rather than trusted.
 | `mapStyle` | `"name+required" \| "explicit" \| "signature"` | `"name+required"` | level 3 only |
 | `namespaceOf` | `(name) => {ns, op}` | split on first `_`/`.` | levels 2–3 grouping |
 | `aliasOf` | `(ns) => string` | identity | level 2 tool naming |
+| `signaturePrefix` | `boolean` | `true` | level 1 only; see below |
 | `searchLimit` | `number` | `8` | max results from a `q` search |
 | `validate` | `boolean` | `true` | **leave this on** |
 | `model` | `string` | — | exact model id; picks the measured style. Omit and nothing changes |
 | `objective` | `"occupancy" \| "cost"` | `"occupancy"` | what the pick optimises. Only `cost` has entries |
 
+#### `signaturePrefix` — measured, and not the default for a reason
+
+Level 1 prepends `name(a,b?) — ` to each description while keeping the full
+`input_schema`. That prefix restates the tool name, property names, required list, enums
+and item types that the schema already carries, and it is **18.5% of the level-1
+payload** on the real corpus. Setting it `false` makes level 1 strictly smaller — 45.2%
+→ **55.3%** on 149 real tools — and removes the case where level 1 *inflates* a terse
+catalogue at all (−14.4% → −0.6%, which is level 0's own floor).
+
+It stays `true` by default because size was not the question. Over 64 live runs, removing
+it was a clear win on three providers and **not** on the fourth:
+
+| Provider | Block | Median cost | Turns |
+|---|---:|---:|---|
+| `gemini-3.1-pro-preview` | −18.5% | −15.3% | 2.00 → 2.00 |
+| `gpt-5.6-sol` | −26.0% | −13.8% | 2.38 → 2.13 |
+| `grok-4.5` | −18.2% | −17.2% | 3.00 → 3.00 |
+| `claude-opus-5` | −18.3% | **+3.8%** | **3.88 → 4.63** |
+
+On `claude-opus-5` the smaller block is spent on extra turns, and one turn is worth
+~3,300 prompt tokens here. **Zero malformed arguments and zero hallucinated names on both
+arms, 64/64 tasks.** So it is safe either way; it is just not universally cheaper. Try it
+if you are not on Anthropic, and measure. Full write-up in
+[docs/RESULTS.md](docs/RESULTS.md) Round 7.
+
 Returns:
 
 | Field | Type | Notes |
@@ -964,13 +1035,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/index.js

@@ -228,11 +228,14 @@ export function compress(input, options = {}) {
     // Level 1 — signature flattening, native tools, real names
     // -------------------------------------------------------------------------
     if (level === 1) {
+        const withSig = options.signaturePrefix ?? true;
         const wire = tools.map((t) => {
             const d = firstSentence(t.description);
+            // With no description the signature is the only content there is, so it stays
+            // regardless — an empty description would leave the model nothing to read.
             return {
                 name: t.name,
-                description: d ? `${signatureLine(t)} — ${d}` : signatureLine(t),
+                description: withSig || !d ? (d ? `${signatureLine(t)} — ${d}` : signatureLine(t)) : d,
                 input_schema: flattenSchema(t.schema),
             };
         });

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/dist/types.d.ts

@@ -80,6 +80,24 @@ export type CompressOptions = {
     };
     /** Override the short alias used for a namespace at level 2. */
     aliasOf?: (ns: string) => string;
+    /**
+     * Level 1 only. Prepend `name(a,b?)` to each description. Default true, which is
+     * the historical behaviour and what every published level-1 figure was measured with.
+     *
+     * **Experimental, and measured before it may become a default.** The prefix is fully
+     * redundant with the `input_schema` level 1 retains — the model already has the tool
+     * name, the property names, the required list, the enums and the item types — and it
+     * costs 18.5% of the level-1 payload on the real 149-tool corpus. Setting this false
+     * makes level 1 strictly smaller and removes the case where level 1 *inflates* a
+     * terse catalogue.
+     *
+     * It is not the default because "smaller" is not the question. Every arm that
+     * measured clean — zero malformed arguments, no extra turns — had the prefix, and a
+     * one-line signature may be easier for a model to read than the equivalent JSON.
+     * Whether that matters at level 1, where the schema is present anyway, is a
+     * benchmark result and not yet in hand.
+     */
+    signaturePrefix?: boolean;
     /** Cap how many results a search/query meta-call returns. Default 8. */
     searchLimit?: number;
     /** Validate arguments against the original schema before dispatch. Default true. */

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% |
 
@@ -164,8 +170,15 @@ recommendLevel(tools, namespaceOf?) → { level, reason, toolCount, namespaceCou
 selectMapStyle(options) → { mapStyle, requestedMapStyle?, fallbackReason? }   // pure
 ```
 
-`CompressOptions`: `level`, `mapStyle`, `namespaceOf`, `aliasOf`, `searchLimit`,
-`validate`, `model`, `objective`.
+`CompressOptions`: `level`, `mapStyle`, `namespaceOf`, `aliasOf`, `signaturePrefix`,
+`searchLimit`, `validate`, `model`, `objective`.
+
+`signaturePrefix` (level 1, default true) controls the `name(a,b?) — ` prefix on each
+description. Setting it false makes level 1 smaller — 45.2% → 55.3% on real MCP tools —
+and measured cheaper on Gemini, OpenAI and xAI over 64 runs. On `claude-opus-5` it was
+**+3.8% dearer** because turns rose 3.88 → 4.63. Safe either way (zero malformed
+arguments on both arms); not universally cheaper. Do not set it without measuring your
+own workload.
 
 `CompressResult`: `tools`, `systemPreamble`, `cachePreamble`, `resolve()`, `codeFor()`,
 `encodeCallForTest()`, `stats`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolgz",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Compress LLM tool definitions to reclaim context window. Measured across Anthropic, OpenAI, Google and xAI.",
   "main": "dist/index.js",
   "scripts": {
@@ -12,7 +12,10 @@
     "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",
+    "demo": "tsx demo/cli.ts",
+    "bench:noprefix": "tsx -r dotenv/config bench/harness/run-multi.ts --provider=all --suite=real --variants --arms=signatures,signatures-noprefix --reps=2 --scenario=real-daily-vs-weekly,real-overwrite-vs-append,real-status-vs-result,real-rollup-vs-detail"
   },
   "keywords": [
     "llm",