toolgz 0.2.9 → 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> ·
@@ -15,6 +15,17 @@ zero runtime dependencies ·
 npm install toolgz
 ```
 
+> ### 🤖 If a coding agent is reading this
+>
+> Point it at **[`llms.txt`](llms.txt)** — prescriptive integration instructions written
+> for an agent, shipped inside the package at `node_modules/toolgz/llms.txt`. It covers
+> the three-step contract, the rules that are not optional, per-model behaviour, and a
+> `Do not` list of the mistakes we have actually fielded.
+>
+> ```
+> Read node_modules/toolgz/llms.txt before integrating toolgz.
+> ```
+
 ---
 
 ## The problem
@@ -33,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
 ```
@@ -43,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.
@@ -67,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.
@@ -195,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
@@ -203,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>
@@ -232,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.
 
@@ -256,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
 ```
 
@@ -286,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";
@@ -421,6 +448,10 @@ than a bug report from you.
 npx tsx examples/01-minimal.ts
 ```
 
+**[`examples/README.md`](examples/README.md) walks through all five** with their real
+output and what each one is trying to teach — start there if you would rather read than
+run.
+
 | File | Shows |
 |---|---|
 | [`01-minimal.ts`](examples/01-minimal.ts) | the smallest useful thing: `recommendLevel` → `compress` → `resolve` |
@@ -949,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

@@ -0,0 +1,211 @@
+# toolgz
+
+> Compresses LLM tool definitions to reclaim context window. Zero runtime dependencies,
+> TypeScript, Apache-2.0. Works with any model and any framework: it transforms a tool
+> array before you send it, and translates the model's call back afterwards.
+
+**This file is written for a coding agent integrating toolgz into a project.** It is
+prescriptive on purpose. If you are contributing to toolgz itself, read `AGENTS.md` in the
+repository instead — different audience, different rules.
+
+Installed copy lives at `node_modules/toolgz/llms.txt`. Full prose docs: `README.md`.
+
+---
+
+## The whole integration, correctly
+
+```ts
+import { compress, recommendLevel, forAnthropic } from "toolgz";
+
+// 1. Decide the level ONCE, at startup — not per request.
+const { level } = recommendLevel(myTools);
+const c = compress(myTools, { level });
+
+// 2. Send c.tools instead of your tool array, and append the preamble to your system prompt.
+const { tools, system } = forAnthropic(c);
+
+// 3. Translate every tool call back before you dispatch.
+for (const block of res.content.filter((b) => b.type === "tool_use")) {
+  const r = c.resolve(block.name, block.input);
+  if (r.kind === "call") {
+    const out = await myDispatch(r.name, r.args);      // real name, real args
+    results.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(out) });
+  } else if (r.kind === "meta") {
+    // toolgz answered a lookup itself. DO NOT dispatch. Return its text to the model.
+    results.push({ type: "tool_result", tool_use_id: block.id, content: r.result });
+  } else {
+    // Recoverable by design: hand the message back and the model retries.
+    results.push({ type: "tool_result", tool_use_id: block.id, content: `Error: ${r.message}`, is_error: true });
+  }
+}
+```
+
+Those three steps are the entire contract. `myDispatch` receives exactly what it received
+before toolgz existed.
+
+## Rules that are not optional
+
+1. **`resolve()` every tool call.** At level 3 the model emits opaque codes (`t(f="a0")`),
+   so dispatching `block.name` directly will fail or dispatch the wrong tool. Route
+   everything through `resolve()` even at level 0, so the level becomes a one-line change.
+
+2. **Handle all three `kind` values.** `call` → dispatch. `meta` → toolgz already answered
+   a lookup; return `r.result` to the model and dispatch nothing. `error` → return
+   `r.message` to the model as an error tool_result; do **not** throw. The `error` path is
+   the recovery mechanism, not a failure.
+
+3. **Send the system preamble.** At level 3 the tool map lives in the system prompt. Drop
+   it and the model has no idea what any code means. It is `""` at levels 0–1, so
+   appending it unconditionally is always safe.
+
+4. **`compress()` never changes level on its own.** `compress(tools)` is level 1 forever,
+   2 tools or 500. `recommendLevel()` *advises*; you pass its answer in as `{ level }`.
+   Deliberate: level 3 moves argument validation from the provider to toolgz, which is not
+   a change to make behind a caller's back.
+
+5. **Leave `validate` on** (the default). Levels 2–3 give up the provider's constrained
+   decoding, so toolgz validating against the original schema is what catches malformed
+   arguments. On a weak model, disabling it converts roughly half of all runs from a
+   recovered retry into a bad dispatch.
+
+6. **Compress once, reuse the result.** `compress()` is deterministic — same tools in,
+   byte-identical payload out — so the output is prompt-cache friendly. Recomputing per
+   request is wasted work; changing the tool list mid-conversation invalidates the cache
+   and strands codes the model has already seen.
+
+## Choosing a level
+
+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% 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% |
+
+The switch is the **size** of the level-1 block, not the tool count — threshold 10,000
+tokens (~5% of a 200k window). A tool is 20 to 460 tokens depending on schema verbosity,
+so 40 real MCP tools cross it while 72 one-parameter tools do not.
+
+Level 2 is dominated by level 3 on accuracy (six times the malformed arguments) and is
+never recommended. It stays in the API for callers who need real operation names.
+
+## Provider adapters — pick the right one
+
+```ts
+forAnthropic(c, { cache?, ttl? })  // → { tools, system }        Messages API
+forOpenAI(c)                       // → { tools, systemPreamble } /v1/chat/completions
+forOpenAIResponses(c)              // → { tools, systemPreamble } /v1/responses
+forGemini(c)                       // → { tools, systemPreamble } generateContent
+```
+
+Two mistakes that produce confusing provider errors:
+
+- **OpenAI has two incompatible tool shapes.** `/v1/chat/completions` wants nested
+  `{type, function:{…}}`; `/v1/responses` wants flat `{type, name, …}`. If you set
+  reasoning effort on a GPT-5.x model you must use `/v1/responses`, therefore
+  `forOpenAIResponses`. Using the wrong adapter is rejected at the API.
+- **Gemini returns ONE wrapper object,** not one entry per tool. Read
+  `tools[0].functionDeclarations.length`; `tools.length` is always 1.
+
+`forGemini` also repairs three schema forms Gemini rejects with a 400: an array-valued
+`type`, `type: "array"` with no `items`, and a non-string `enum`. Constraints stripped to
+satisfy Gemini are still enforced by `resolve()` against your original schema — nothing is
+silently dropped.
+
+xAI is OpenAI-compatible: use `forOpenAI` with `baseURL: "https://api.x.ai/v1"`. **xAI
+caps tool arrays at 350**; other providers accept 1,200+. Level 3 sends 2 either way.
+
+## Model-specific behaviour
+
+Pass an exact model id and toolgz uses the best *measured* map style for it:
+
+```ts
+compress(myTools, { level: 3, model: "gpt-5.6-sol", objective: "cost" });
+```
+
+| Model | `objective: "cost"` | Measured vs default |
+|---|---|---:|
+| `gpt-5.6-sol` | `explicit` | −20.7% |
+| `gemini-3.1-pro-preview` | `explicit` | −15.4% |
+| `claude-opus-5` | `explicit` | −9.0% |
+| `grok-4.5` | *(no entry)* | `explicit` is **+13.2%** there |
+
+- Model ids are **exact, never families**. A result for `gpt-5.6-sol` says nothing about
+  `gpt-5.7`. An unknown model gets the conservative default — absence of evidence, not a
+  prediction.
+- The default objective is `occupancy`, which has **no** entries: nothing beat the default
+  by more than 3.1% on that axis, under the 5% effect-size floor. Only `cost` has rows.
+- This is the one thing the library picks for you, and only when you pass `model`. A map
+  style is a pure encoding choice, so a better one cannot change results. The *level*
+  can — which is why that stays explicit.
+- Do not set `mapStyle` by hand unless you have measured your own workload. Prefer
+  `model` + `objective`.
+
+## MCP servers
+
+`tools/list` returns `{ name, description, inputSchema }` per tool — exactly what
+`compress()` accepts. **There is no adapter layer.** Merge the arrays from every server
+and pass them in.
+
+`input_schema` and `inputSchema` are both accepted, so Anthropic-shaped and MCP-shaped
+tools can be mixed.
+
+Watch for name collisions when merging catalogues from independent servers. If two tool
+names normalise identically, toolgz refuses to alias either one rather than guess — the
+map code still works.
+
+## API surface
+
+```ts
+compress(tools, options?) → CompressResult
+recommendLevel(tools, namespaceOf?) → { level, reason, toolCount, namespaceCount, opsPerNamespace }
+selectMapStyle(options) → { mapStyle, requestedMapStyle?, fallbackReason? }   // pure
+```
+
+`CompressOptions`: `level`, `mapStyle`, `namespaceOf`, `aliasOf`, `searchLimit`,
+`validate`, `model`, `objective`.
+
+`CompressResult`: `tools`, `systemPreamble`, `cachePreamble`, `resolve()`, `codeFor()`,
+`encodeCallForTest()`, `stats`.
+
+`stats`: `level`, `mapStyle`, `requestedMapStyle`, `fallbackReason`, `toolCount`,
+`wireToolCount`, `originalChars`, `compressedChars`, `savedPct`.
+
+`namespaceOf` must return `{ ns, op }`, **not** a bare string. Returning a string throws
+with a corrected example — it used to fail silently and produce a plausible-looking but
+wrong map.
+
+## Things to tell the user, not assume
+
+- **`savedPct` is a CHARACTER saving**, a few points optimistic against tokens. Providers
+  charge a fixed framing cost per tool definition that character counting cannot see. For
+  any published figure, measure with the provider's own token counter.
+- **Never use `tiktoken` to count Claude tokens** — it is OpenAI's tokenizer and is wrong
+  for Claude by 15–20%+. Use Anthropic's `count_tokens`.
+- **Token saving ≠ cost saving.** Prompt caching already makes tool tokens cheap; the claim
+  here is context-window *occupancy*. Cost follows by a variable amount, and on OpenAI —
+  where reasoning output dominates the bill — it was as little as 7%.
+- **Level 3 costs turns.** Roughly 0.3–1.7 lookup calls per task, about half an extra turn.
+  If latency matters more than context, stay at level 1.
+- **Below the frontier tier, argument formatting degrades at level 3.** On Haiku 4.5, 17 of
+  30 runs produced a malformed argument — all caught by `validate` and recovered, no task
+  lost, but that is the known edge. Tool *choice* did not degrade.
+
+## Do not
+
+- Do not dispatch `block.name` without `resolve()`.
+- Do not throw on `kind: "error"` — return it to the model.
+- Do not dispatch on `kind: "meta"`.
+- Do not omit `systemPreamble` at level 3.
+- Do not set `validate: false` to silence a malformed-argument error; fix the schema.
+- Do not call `compress()` inside the request loop.
+- Do not report `savedPct` as a token or cost saving.
+- Do not assume a level was chosen for you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolgz",
-  "version": "0.2.9",
+  "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",
@@ -45,6 +46,7 @@
   "files": [
     "dist",
     "README.md",
+    "llms.txt",
     "LICENSE",
     "NOTICE"
   ],