toolgz 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 <h1>toolgz</h1>
 
-<p><strong>Your agent spends 30–50k tokens of context on tool definitions before the user types a word. toolgz gets ~80% of it back.</strong></p>
+<p><strong>Your agent spends 30–70k tokens of context on tool definitions before the user types a word. toolgz gets ~80% of it back.</strong></p>
 
 <p>
 <a href="#measured-results">420-run cross-provider sweep</a> ·
@@ -51,24 +51,77 @@ if (r.kind === "call") await myDispatch(r.name, r.args);   // real name, real ar
 Four frontier models, seven strategies, five tool-selection tasks, 3 reps —
 **420 runs** on the current sweep, 1,200+ across all rounds. Every raw per-run record is
 committed in [`bench/results/`](bench/results/); recompute any figure with
-`npx tsx bench/analyze-multi.ts`.
+`npx tsx bench/analyze-multi.ts --sweep=<timestamp>`.
+
+**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:
+
+- 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.
+  On real MCP tools, which mostly do not, the same style was worth −1%.
+- Real catalogues are **bigger**, so these numbers understate the problem. A corpus of
+  **149 tools harvested from 14 live MCP servers** measures **68,494 prompt tokens**
+  uncompressed on `claude-opus-5` — more than twice the synthetic fixture, and about a
+  third of a 200k context window before the user types anything.
+
+The real corpus is committed at [`bench/fixtures/real-mcp-tools.json`](bench/fixtures/real-mcp-tools.json)
+with its own scenario suite (`--suite=real`), and it is the corpus of record for any
+claim about real deployments.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/img/savings-dark.svg">
   <img src="docs/img/savings-light.svg" alt="Prompt tokens saved versus uncompressed tool definitions, by compression level, for each of four providers">
 </picture>
 
-| Provider | Model | Tool block | Prompt tokens | Cost | Latency | Tasks |
-|---|---|---:|---:|---:|---:|:-:|
-| Anthropic | `claude-opus-5` | 9,242 → **1,284** | 30,817 → **4,628** (−85%) | **−78%** | 15.0s → **12.1s** | 15/15 |
-| xAI | `grok-4.5` | 6,421 → **775** | 17,522 → **2,663** (−85%) | **−70%** | 6.1s → **4.6s** | 15/15 |
-| Google | `gemini-3.1-pro-preview` | 5,264 → **732** | 10,948 → **2,302** (−79%) | **−62%** | 5.6s → **5.5s** | 15/15 |
-| OpenAI | `gpt-5.6-sol` | 2,752 → **573** | 7,694 → **2,196** (−71%) | **−7%** | 6.8s → **5.6s** | 15/15 |
+| Provider | Model | Tool block | Prompt tokens | Latency | Tasks |
+|---|---|---:|---:|---:|:-:|
+| Anthropic | `claude-opus-5` | 9,242 → **1,284** | 30,817 → **4,628** (**−85%**) | 15.0s → **12.1s** | 15/15 |
+| xAI | `grok-4.5` | 6,421 → **775** | 17,522 → **2,663** (**−85%**) | 6.1s → **4.6s** | 15/15 |
+| Google | `gemini-3.1-pro-preview` | 5,264 → **732** | 10,948 → **2,302** (**−79%**) | 5.6s → **5.5s** | 15/15 |
+| OpenAI | `gpt-5.6-sol` | 2,752 → **573** | 7,694 → **2,196** (**−71%**) | 6.8s → **5.6s** | 15/15 |
 
 Reasoning is enabled on all four at high effort, so this is a like-for-like frontier
 comparison. **60/60 tasks completed, zero hallucinated tool names, zero malformed
 arguments** — and it is faster than uncompressed on every provider.
 
+Recompute any figure with
+`npx tsx bench/analyze-multi.ts --sweep=2026-07-25T19-19` against the raw per-run
+records in [`bench/results/`](bench/results).
+
+### What about cost?
+
+**Cost is not the claim, and we deliberately do not lead with it.** Prompt caching
+already makes tool tokens cheap. What caching does not do is give you the *room* back,
+and the room is what you run out of.
+
+Cost does usually fall as a side effect, by an amount that depends on your provider
+and reasoning settings — and on one of four providers we measured, it does not fall at
+all. On `gpt-5.6-sol` the uncompressed cost distribution is heavily right-skewed (mean
+$0.0172, median $0.0052), so a few expensive runs make compression look break-even
+while the *typical* run gets about 2.5× dearer. We used to publish a "−7% on OpenAI"
+figure. It was a mean over a skewed distribution and we withdrew it.
+
+If you do want to optimise the bill, it is one option — and it is a trade, not a
+freebie:
+
+```ts
+compress(myTools, { level: 3, model: "gpt-5.6-sol", objective: "cost" });
+```
+
+| Model | Median cost vs default |
+|---|---:|
+| `gpt-5.6-sol` | **−20.7%** |
+| `gemini-3.1-pro-preview` | **−15.4%** |
+| `claude-opus-5` | **−9.0%** |
+| `grok-4.5` | **+13.2%** — so it is not enabled there |
+
+From 432 runs, 36 per style per provider, on the real 149-tool corpus. **What you give
+up:** a slightly larger cached map (+275 characters), and on `grok-4.5` a worse bill —
+which is why that row keeps the default rather than the cost-optimised style. Omit
+`objective` and you get the conservative default everywhere, unchanged.
+
 ### It does not make the model worse
 
 That was the thing to disprove, and we tried hard to. The task suite is built from
@@ -86,26 +139,28 @@ 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.
 
-### Cost, and why it took two rounds to get right
+### How we found the cost story, and got it wrong twice
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/img/cost-dark.svg">
-  <img src="docs/img/cost-light.svg" alt="Prompt tokens and cost both reduced on all four providers">
+  <img src="docs/img/cost-light.svg" alt="Prompt tokens and cost, by compression level, for each of four providers">
 </picture>
 
-The first cross-provider sweep found cost going **up 15% on OpenAI** even while context fell
-69%. The dispatcher was spending extra turns, and on a reasoning model every turn pays for a
-fresh round of thinking.
+The first cross-provider sweep found cost going **up 15% on OpenAI** even while context
+fell 69%. The dispatcher was spending extra turns, and on a reasoning model every turn
+pays for a fresh round of thinking.
 
-So we captured the calls that were being rejected instead of guessing, and found three bugs
-in *this library*: models pass `query` to a parameter named `q` (14 of 18 rejections), they
-sometimes call the map code as the tool name, and they sometimes pass arguments flat instead
-of nested. Fixing all three took OpenAI from **+15% to −7%** and drove malformed arguments to
-**zero on every provider**.
+So we captured the calls being rejected instead of guessing, and found three bugs in
+*this library*: models pass `query` to a parameter named `q` (14 of 18 rejections), they
+sometimes call the map code as the tool name, and they sometimes pass arguments flat
+instead of nested. Fixing all three drove malformed arguments to **zero on every
+provider**. Later rounds found three more of the same kind — a namespace joined with a
+dot, the lookup tool routed through the dispatcher — all shipped in 0.1.2.
 
-OpenAI's −7% is still the smallest saving, and honestly so: reasoning output dominates its
-bill, so a smaller prompt moves the total less. **Context-window occupancy remains the
-primary claim** — cost follows from it, by an amount that depends on your reasoning settings.
+That is the honest shape of this work: **most of the wins came from accepting what
+models actually send, not from making the map smaller.** One extra turn is worth ~3,300
+prompt tokens; the best encoding change available was worth ~550. Six map styles were
+tried and removed in 0.2.0 because they were smaller and still worse.
 
 ---
 
@@ -168,6 +223,56 @@ trip. A test asserts that file matches the code, so it cannot drift.
 
 ---
 
+## Optional: let the library pick the map style for your model
+
+Level 3 has several map styles. Which one is cheapest turns out to depend on the
+model, so you can hand `compress()` a model id and let it use what was actually
+measured:
+
+```ts
+compress(myTools, { level: 3, model: "gpt-5.6-sol", objective: "cost" });
+```
+
+| Model | Style chosen for `cost` | Measured against the 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` | *default* | `explicit` measured **+13.2%** there |
+
+From a 432-run sweep, 36 runs per style per provider, on the real 149-tool corpus.
+`explicit` completed 144/144 tasks and cut lookups on all four providers; only the
+*cost* consequence differs by model. The table lives in
+[`src/policy.generated.ts`](src/policy.generated.ts), is generated from the committed
+results, and a test fails if it drifts from them.
+
+Four things worth knowing:
+
+- **Omitting `model` changes nothing.** Existing behaviour is byte-identical; there
+  is a test asserting that.
+- **`objective` defaults to `occupancy`, which has no table.** Every style we
+  measured landed within ±3.1% of the default on context occupancy — under our 5%
+  effect-size floor — so there is nothing to select. Only `cost` has entries.
+- **An absent model gets the default.** That is an absence of evidence, not a
+  prediction. `gpt-5.6-sol` behaving one way says nothing certain about `gpt-5.7`.
+- **`stats` always tells you what was actually used**, so nothing is substituted
+  silently:
+
+```ts
+const c = compress(myTools, { level: 3, model: "gpt-5.6-sol", objective: "cost" });
+c.stats.mapStyle;          // "explicit" — what was used
+c.stats.requestedMapStyle; // undefined — you did not ask for a specific style
+c.stats.fallbackReason;    // undefined — nothing was substituted
+```
+
+There is also a safety valve: if a future sweep finds a `(model, style)` pair that
+fails, it is refused and `stats.fallbackReason` says why. **That table is currently
+empty** — the one pair ever measured unsafe was `nocode` on `grok-4.5` (19% of runs
+answered with no tool call at all), and rather than document a footgun we deleted the
+style in 0.2.0.
+
+---
+
 ## Documentation
 
 | | |

package/dist/index.d.ts

@@ -13,9 +13,28 @@
  *     if (r.kind === "call") await myDispatch(r.name, r.args);
  *   }
  */
-import type { CompressOptions, CompressResult, Tool } from "./types.js";
+import type { CompressOptions, CompressResult, Tool, MapStyle } from "./types.js";
+import type { PolicyEntry, BrokenEntry } from "./policy.generated.js";
 export * from "./types.js";
 export { flattenSchema, signatureLine, countSchemaTokensApprox } from "./render/index.js";
+export { POLICY, BROKEN, CONSERVATIVE_DEFAULT } from "./policy.generated.js";
+export type { PolicyEntry, BrokenEntry, Objective } from "./policy.generated.js";
+/**
+ * Choose the level-3 map style, and report anything it had to substitute.
+ *
+ * Pure and exported so the disallow path is testable against synthetic tables. It
+ * used to be inline in `compress()`, which meant it could only be exercised through
+ * a real BROKEN entry — and once the one unsafe style was removed from the library
+ * there were none, leaving the safety valve untested.
+ *
+ * Order: an explicit request wins unless measured unsafe for that model; then the
+ * measured policy for (model, objective); then the conservative default.
+ */
+export declare function selectMapStyle(options: Pick<CompressOptions, "mapStyle" | "model" | "objective">, policy?: readonly PolicyEntry[], broken?: readonly BrokenEntry[]): {
+    mapStyle: MapStyle;
+    requestedMapStyle?: MapStyle;
+    fallbackReason?: string;
+};
 export declare function compress(input: Tool[], options?: CompressOptions): CompressResult;
 export { recommendLevel } from "./recommend.js";
 export type { Recommendation } from "./recommend.js";

package/dist/index.js

@@ -1,10 +1,16 @@
-import { countSchemaTokensApprox, defaultNamespaceOf, firstSentence, flattenSchema, normalize, signatureLine, terseDescriptor, } from "./render/index.js";
+import { countSchemaTokensApprox, defaultNamespaceOf, firstSentence, flattenSchema, normalize, signatureLine, } from "./render/index.js";
 import { validateArgs } from "./runtime/validate.js";
+import { nearest } from "./runtime/similar.js";
+import { POLICY, BROKEN, CONSERVATIVE_DEFAULT } from "./policy.generated.js";
 export * from "./types.js";
 export { flattenSchema, signatureLine, countSchemaTokensApprox } from "./render/index.js";
+// Exported so consumers can see WHY a style was chosen. The generated file is not in
+// the published tarball (only dist/ ships), so without this the policy is a black box
+// and the README could point at something a user cannot read.
+export { POLICY, BROKEN, CONSERVATIVE_DEFAULT } from "./policy.generated.js";
 const CODE_CHARS = "abcdefghijklmnopqrstuvwxyz";
 const LEVELS = [0, 1, 2, 3];
-const MAP_STYLES = ["name", "name+required", "signature", "terse"];
+const MAP_STYLES = ["name+required", "explicit", "signature"];
 const err = (message, recoverable = true) => ({
     kind: "error",
     message,
@@ -29,6 +35,41 @@ function asObject(v) {
 function defaultAlias(ns) {
     return ns;
 }
+/**
+ * Choose the level-3 map style, and report anything it had to substitute.
+ *
+ * Pure and exported so the disallow path is testable against synthetic tables. It
+ * used to be inline in `compress()`, which meant it could only be exercised through
+ * a real BROKEN entry — and once the one unsafe style was removed from the library
+ * there were none, leaving the safety valve untested.
+ *
+ * Order: an explicit request wins unless measured unsafe for that model; then the
+ * measured policy for (model, objective); then the conservative default.
+ */
+export function selectMapStyle(options, policy = POLICY, broken = BROKEN) {
+    const objective = options.objective ?? "occupancy";
+    if (options.mapStyle) {
+        const unsafe = options.model
+            ? broken.find((b) => b.model === options.model && b.mapStyle === options.mapStyle)
+            : undefined;
+        if (!unsafe)
+            return { mapStyle: options.mapStyle };
+        // Owner decision: disallow a measured-unsafe pair and fall back, rather than
+        // honour it with a warning. Reported, never silent.
+        return {
+            mapStyle: CONSERVATIVE_DEFAULT,
+            requestedMapStyle: options.mapStyle,
+            fallbackReason: `mapStyle "${options.mapStyle}" is measured unsafe on ${unsafe.model}: ` +
+                `${unsafe.reason} (n=${unsafe.n}, sweep ${unsafe.sweep}). ` +
+                `Using "${CONSERVATIVE_DEFAULT}" instead.`,
+        };
+    }
+    if (options.model) {
+        const hit = policy.find((e) => e.model === options.model && e.objective === objective);
+        return { mapStyle: hit ? hit.mapStyle : CONSERVATIVE_DEFAULT };
+    }
+    return { mapStyle: CONSERVATIVE_DEFAULT };
+}
 export function compress(input, options = {}) {
     const level = (options.level ?? 1);
     if (!LEVELS.includes(level)) {
@@ -43,7 +84,7 @@ export function compress(input, options = {}) {
     // 60/60 tasks, fewer malformed arguments, fewer lookup round-trips, and
     // faster wall-clock than uncompressed on every provider. The larger map pays
     // for itself by removing a discovery turn.
-    const mapStyle = options.mapStyle ?? "name+required";
+    const { mapStyle, requestedMapStyle, fallbackReason, } = selectMapStyle(options, POLICY, BROKEN);
     if (!MAP_STYLES.includes(mapStyle)) {
         throw new Error(`unsupported mapStyle: ${mapStyle} (expected ${MAP_STYLES.join(", ")})`);
     }
@@ -79,6 +120,44 @@ export function compress(input, options = {}) {
             });
         }
     }
+    /**
+     * Separator-insensitive lookup for level-3 map keys.
+     *
+     * Observed on gpt-5.6-sol against real MCP tools: the model reassembled a
+     * namespaced name with a DOT where the real tool uses an underscore —
+     * `gdrive.sheets_append_rows`, `coding.task_result`, `reverse.geocode`. Joining a
+     * namespace and an operation with `.` is the ordinary convention for qualified
+     * identifiers, so the inference is reasonable and ours was simply too strict.
+     * Rejecting it burned six turns per task.
+     *
+     * Keys are therefore compared with every separator stripped, which accepts `.`,
+     * `:`, `/`, `-`, a space, or nothing. Registered ONLY where the normalised form
+     * is unambiguous: if two tools normalise alike neither is aliased and the exact
+     * name is required, so this can never silently dispatch the wrong tool.
+     */
+    const normKey = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const normIndex = new Map();
+    const registerNorm = (key, t) => {
+        const k = normKey(key);
+        if (!k)
+            return;
+        const seen = normIndex.get(k);
+        if (seen === undefined)
+            normIndex.set(k, t); // first claim
+        else if (seen && seen.name !== t.name)
+            normIndex.set(k, null); // ambiguous
+    };
+    if (level === 3) {
+        for (const t of tools)
+            registerNorm(t.name, t);
+        for (const [code, t] of codeToTool)
+            registerNorm(code, t);
+    }
+    /** Exact map key first, then the separator-insensitive fallback. */
+    const lookupMapKey = (raw) => {
+        const key = String(raw ?? "");
+        return codeToTool.get(key) ?? normIndex.get(normKey(key)) ?? undefined;
+    };
     const finish = (wire, systemPreamble, cachePreamble, resolve, encode) => {
         const compressedChars = countSchemaTokensApprox(wire) + systemPreamble.length;
         return {
@@ -95,6 +174,9 @@ export function compress(input, options = {}) {
             encodeCallForTest: encode,
             stats: {
                 level,
+                mapStyle,
+                requestedMapStyle: requestedMapStyle && requestedMapStyle !== mapStyle ? requestedMapStyle : undefined,
+                fallbackReason,
                 toolCount: tools.length,
                 wireToolCount: wire.length,
                 originalChars,
@@ -217,16 +299,16 @@ export function compress(input, options = {}) {
     // against a full schema's ~400 — to reduce malformed arguments on models that
     // fill the generic argument bag poorly.
     const renderLine = (code, t) => {
-        if (mapStyle === "terse")
-            return `${code} ${terseDescriptor(t.description) || t.name}`;
+        const req = t.schema.required ?? [];
         // Full signature: optional params included, so the model rarely needs q().
         if (mapStyle === "signature")
             return `${code} ${signatureLine(t)}`;
-        if (mapStyle === "name+required") {
-            const req = t.schema.required ?? [];
-            return req.length ? `${code} ${t.name} ${req.join(",")}` : `${code} ${t.name}`;
-        }
-        return `${code} ${t.name}`;
+        if (req.length)
+            return `${code} ${t.name} ${req.join(",")}`;
+        // No required parameters. `explicit` says so, because a bare name is
+        // indistinguishable from a tool whose parameters were omitted, and the model
+        // spends a lookup finding out it could have just called it.
+        return mapStyle === "explicit" ? `${code} ${t.name} ()` : `${code} ${t.name}`;
     };
     const lines = [...codeToTool.entries()].map(([code, t]) => renderLine(code, t));
     const wire = [
@@ -251,17 +333,32 @@ export function compress(input, options = {}) {
             },
         },
     ];
-    const mapLegend = mapStyle === "name+required"
-        ? "Each line is: code name required-args. "
-        : mapStyle === "signature"
-            ? "Each line is: code name(args), where ? marks optional. "
-            : "";
-    const systemPreamble = `<toolmap>\n${lines.join("\n")}\n</toolmap>\n${mapLegend}Invoke with t(f=<code>, a={…}). Use q to expand a code before calling if you are unsure of its parameters.`;
-    return finish(wire, systemPreamble, true, (name, rawArgs) => {
-        const args = asObject(rawArgs);
+    const mapLegend = mapStyle === "signature"
+        ? "Each line is: code name(args), where ? marks optional. "
+        : mapStyle === "explicit"
+            ? "Each line is: code name required-args. A line ending in () takes no required arguments and can be called with none. "
+            : "Each line is: code name required-args. ";
+    const invokeHint = "Invoke with t(f=<code>, a={…}). Use q to expand a code before calling if you are unsure of its parameters.";
+    const systemPreamble = `<toolmap>\n${lines.join("\n")}\n</toolmap>\n${mapLegend}${invokeHint}`;
+    return finish(wire, systemPreamble, true, (rawName, rawArgs) => {
+        let name = rawName;
+        let args = asObject(rawArgs);
+        // Observed on grok-4.5, on every level-3 map style: the model routes the
+        // lookup tool through the dispatcher — t(f="q", a={s:"…"}) instead of
+        // q(s="…"). The preamble invites it, saying "Invoke with t(f=<code>, a={…})"
+        // and then "Use q to expand a code", which reads as everything going through
+        // t. Tasks still completed, so this surfaced as wasted turns rather than as
+        // failure. `t` and `q` are our own reserved names, so the intent is
+        // unambiguous — nothing else could be meant.
+        if (name === "t" && (args.f === "q" || args.f === "t")) {
+            const nested = asObject(args.a);
+            const flat = Object.fromEntries(Object.entries(args).filter(([k]) => k !== "f" && k !== "a"));
+            name = String(args.f);
+            args = Object.keys(nested).length ? nested : flat;
+        }
         if (name === "q") {
             if (args.c !== undefined) {
-                const t = codeToTool.get(String(args.c));
+                const t = lookupMapKey(args.c);
                 if (!t)
                     return err(`No map code "${args.c}". Search with q(s=…).`);
                 return {
@@ -286,13 +383,17 @@ export function compress(input, options = {}) {
         // claude-opus-5: name="b5", args={f:"b5", a:"{…}"}. Codes are unique and
         // cannot collide with `t` or `q`, so this form is unambiguous and
         // accepting it removes a whole class of wasted turn.
-        const viaCode = name !== "t" && name !== "q" ? codeToTool.get(name) : undefined;
+        const viaCode = name !== "t" && name !== "q" ? lookupMapKey(name) : undefined;
         if (!viaCode && name !== "t") {
             return err(`No tool named "${name}". Invoke tools with t(f=<code>).`);
         }
-        const t = viaCode ?? codeToTool.get(String(args.f));
-        if (!t)
-            return err(`No map code "${args.f}". Search with q(s=…).`);
+        const t = viaCode ?? lookupMapKey(args.f);
+        if (!t) {
+            // A near miss is the common case, and a bare rejection costs another turn.
+            const guess = nearest(String(args.f ?? ""), [...codeToTool.keys()]);
+            return err(`No map code "${args.f}". Search with q(s=…).` +
+                (guess ? ` Did you mean "${guess}"? Use it exactly as written in <toolmap>.` : ""));
+        }
         // Args may arrive nested under `a`, or flat alongside `f`. Prefer `a`
         // when present rather than merging, so there is one source of truth.
         const nested = asObject(args.a);

package/dist/policy.generated.d.ts

@@ -0,0 +1,64 @@
+/**
+ * GENERATED — do not edit by hand. Regenerate with:
+ *   npx tsx bench/generate-policy.ts --sweep=<timestamp>
+ *
+ * A record of measurements, not a theory of models. Every row was produced by
+ * `bench/analyze-multi.ts` scoped to one sweep, compared within a provider, and
+ * filtered to effects of at least 5% — same-arm figures moved by more than that
+ * between n=4 and n=96 during development, so smaller effects are noise.
+ *
+ * Hand-maintaining this would rot exactly the way `bench/` and `src/` diverged
+ * before. A drift test (tests/policy.test.ts) fails if it disagrees with the
+ * committed results.
+ *
+ * There is deliberately NO occupancy table. Every measured difference on that axis
+ * was within ±3.1%, under the floor — so occupancy gets the default, and this file
+ * exists only for the `cost` objective. That is a smaller feature than spec 002
+ * originally described, and it is what the data supports.
+ */
+import type { MapStyle } from "./types.js";
+export type Objective = "occupancy" | "cost";
+export type PolicyEntry = {
+    /** Exact model id. Never a family: gpt-5.6-sol says nothing about gpt-5.7. */
+    model: string;
+    objective: Objective;
+    mapStyle: MapStyle;
+    /** Percent change against the conservative default. Negative is better. */
+    effectPct: number;
+    /** Runs behind this row, per arm. */
+    n: number;
+    /** The sweep it came from, so any row can be re-derived. */
+    sweep: string;
+    measured: string;
+};
+/**
+ * Tier-3 sweep, 432 runs, 36 per arm per provider, 12 real MCP scenarios × 3 reps.
+ * `explicit` was 144/144 tasks; turns and lookups fell on all four providers.
+ * Only rows clearing the 5% floor appear.
+ */
+export declare const POLICY: readonly PolicyEntry[];
+/**
+ * (model, mapStyle) pairs measured as unsafe. A caller asking for one is refused and
+ * falls back, per the owner's decision (#15) to disallow rather than warn.
+ */
+export type BrokenEntry = {
+    model: string;
+    mapStyle: MapStyle;
+    reason: string;
+    n: number;
+    sweep: string;
+};
+/**
+ * Empty, and that is the current truth rather than an oversight.
+ *
+ * The one pair ever measured unsafe was `nocode` on grok-4.5 — a 19% silent
+ * failure rate, the model answering with no tool call at all. In 0.2.0 that style
+ * was removed from the library outright, so the pair can no longer be requested.
+ * Deleting a footgun beats documenting it.
+ *
+ * The mechanism stays because it is the safety valve: if a future sweep finds a
+ * (model, style) pair that fails, it goes here and is refused at the boundary.
+ */
+export declare const BROKEN: readonly BrokenEntry[];
+/** The style used when nothing is known about the model. */
+export declare const CONSERVATIVE_DEFAULT: MapStyle;

package/dist/policy.generated.js

@@ -0,0 +1,27 @@
+/**
+ * Tier-3 sweep, 432 runs, 36 per arm per provider, 12 real MCP scenarios × 3 reps.
+ * `explicit` was 144/144 tasks; turns and lookups fell on all four providers.
+ * Only rows clearing the 5% floor appear.
+ */
+export const POLICY = [
+    { model: "claude-opus-5", objective: "cost", mapStyle: "explicit", effectPct: -9.0, n: 36, sweep: "2026-07-26T03-07-25", measured: "2026-07-26" },
+    { model: "gemini-3.1-pro-preview", objective: "cost", mapStyle: "explicit", effectPct: -15.4, n: 36, sweep: "2026-07-26T03-07-25", measured: "2026-07-26" },
+    { model: "gpt-5.6-sol", objective: "cost", mapStyle: "explicit", effectPct: -20.7, n: 36, sweep: "2026-07-26T03-07-25", measured: "2026-07-26" },
+    // grok-4.5 is deliberately absent for `cost`: explicit measured +13.2% there, so it
+    // falls through to the conservative default. An absent row means "no measured
+    // improvement", never "untested".
+];
+/**
+ * Empty, and that is the current truth rather than an oversight.
+ *
+ * The one pair ever measured unsafe was `nocode` on grok-4.5 — a 19% silent
+ * failure rate, the model answering with no tool call at all. In 0.2.0 that style
+ * was removed from the library outright, so the pair can no longer be requested.
+ * Deleting a footgun beats documenting it.
+ *
+ * The mechanism stays because it is the safety valve: if a future sweep finds a
+ * (model, style) pair that fails, it goes here and is refused at the boundary.
+ */
+export const BROKEN = [];
+/** The style used when nothing is known about the model. */
+export const CONSERVATIVE_DEFAULT = "name+required";

package/dist/render/index.js

@@ -128,7 +128,20 @@ export function normalize(tools, namespaceOf) {
         if (seen.has(t.name))
             throw new Error(`duplicate tool name: ${t.name}`);
         seen.add(t.name);
-        const { ns, op } = namespaceOf(t.name);
+        // Validate the callback's return rather than trusting it. The contract is
+        // easy to get wrong — it takes a name and returns {ns, op}, not a bare
+        // namespace string — and the failure was silent and remote: every tool
+        // collapsed into one `undefined` namespace, level 2 emitted a wire tool with
+        // an empty name, and the first symptom was the provider rejecting the request
+        // with "tools.0.custom.name: Field required", nowhere near the cause.
+        const parts = namespaceOf(t.name);
+        const ns = parts?.ns;
+        const op = parts?.op;
+        if (typeof ns !== "string" || !ns || typeof op !== "string" || !op) {
+            throw new Error(`namespaceOf("${t.name}") must return { ns, op } with non-empty strings, ` +
+                `got ${JSON.stringify(parts)}. ` +
+                `Example: (name) => ({ ns: serverOf(name), op: name }).`);
+        }
         return {
             name: t.name,
             description: t.description ?? "",

package/dist/types.d.ts

@@ -34,27 +34,41 @@ export type NormalizedTool = {
  *  3  minified           — single dispatcher + opaque codes
  */
 export type Level = 0 | 1 | 2 | 3;
+import type { Objective } from "./policy.generated.js";
+export type { Objective };
 /**
  * How each line of the level-3 `<toolmap>` is rendered.
  *
- *   name           `a0 github_create_issue`
- *   name+required  `a0 github_create_issue owner,repo,title`
+ *   name+required  `a0 github_create_issue owner,repo,title`   <- default
+ *   explicit       `a0 github_create_issue owner,repo,title`
+ *                  `a0 scorecard_lf_daily ()`  <- () = takes no required args
  *   signature      `a0 github_create_issue(owner,repo,title,body?,labels?)`
- *   terse          `a0 create new issue in repository`
  *
- * `name` is the default and the smallest. `name+required` costs a few tokens
- * per tool and exists to cut malformed arguments on models that fill the
- * generic argument bag badly — the dispatcher levels give up provider-side
- * constrained decoding, and this buys some of it back cheaply. `signature` also
- * names the optional parameters, which removes most remaining `q()` lookups —
- * a bigger cached map traded for fewer turns, which matters on models where
- * every turn pays for a fresh round of reasoning. `terse` drops the real name
- * entirely; it is the most aggressive and the least legible.
+ * Three styles, each with a measured reason to exist. Six others were tried and
+ * removed in 0.2.0 because they made things worse — see docs/RESULTS.md Round 6.
+ *
+ * `name+required` is the default: the only style perfect on all four providers with
+ * zero malformed arguments. It names required parameters because the dispatcher
+ * levels give up provider-side constrained decoding, and a few tokens per tool buys
+ * some of it back.
+ *
+ * `explicit` adds one thing: a `()` marker on tools that declare no required
+ * parameters. On a real catalogue 44% of tools are like that, and their line would
+ * otherwise be a bare name — indistinguishable from a tool whose parameters were
+ * omitted, so the model spends a lookup finding out it could just call it. Measured
+ * over 432 runs it cut lookups on all four providers and cost 9–21% less on three,
+ * but **13% more on grok-4.5**. Reach for it via `objective: "cost"` rather than
+ * setting it by hand.
+ *
+ * `signature` names optional parameters too, which removes most remaining lookups.
+ * A bigger cached map traded for fewer turns — worth it where every turn pays for a
+ * fresh round of reasoning, and measurably worse on xAI for reasons we cannot yet
+ * explain.
  */
-export type MapStyle = "name" | "name+required" | "signature" | "terse";
+export type MapStyle = "name+required" | "explicit" | "signature";
 export type CompressOptions = {
     level?: Level;
-    /** Level 3 only. Ignored at levels 0–2, which emit no map. Default "name". */
+    /** Level 3 only. Ignored at levels 0–2, which emit no map. Default "name+required". */
     mapStyle?: MapStyle;
     /**
      * Group tools into namespaces. Default splits on the first `_` or `.`,
@@ -70,6 +84,25 @@ export type CompressOptions = {
     searchLimit?: number;
     /** Validate arguments against the original schema before dispatch. Default true. */
     validate?: boolean;
+    /**
+     * Exact model id, e.g. "gpt-5.6-sol". When given, level 3 selects the best
+     * *measured* map style for that model from `src/policy.generated.ts`.
+     *
+     * Never a family: `gpt-5.6-sol` failing says nothing certain about `gpt-5.7`. An
+     * unknown model gets the conservative default — an absence of evidence, not a
+     * prediction. Behaviour is unchanged if you omit this.
+     */
+    model?: string;
+    /**
+     * What the selection optimises. Default "occupancy", because reclaiming context
+     * window is the point — prompt caching already makes tool tokens cheap but does not
+     * reclaim the room they take.
+     *
+     * As measured, "occupancy" currently selects the default on every known model: no
+     * style beat it by more than 3.1% on that axis, under the 5% floor. The table has
+     * real entries only for "cost".
+     */
+    objective?: Objective;
 };
 export type Resolution = {
     kind: "call";
@@ -86,6 +119,12 @@ export type Resolution = {
 };
 export type CompressStats = {
     level: Level;
+    /** The map style actually used. */
+    mapStyle?: MapStyle;
+    /** What the caller asked for, when it differed from what was used. */
+    requestedMapStyle?: MapStyle;
+    /** Why a requested style was not used. Absent when nothing was substituted. */
+    fallbackReason?: string;
     toolCount: number;
     wireToolCount: number;
     originalChars: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolgz",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Compress LLM tool definitions to reclaim context window. Measured across Anthropic, OpenAI, Google and xAI.",
   "main": "dist/index.js",
   "scripts": {
@@ -9,7 +9,10 @@
     "bench": "tsx bench/harness/run.ts",
     "build": "tsc",
     "prepublishOnly": "npm run build && npm test",
-    "test:live": "vitest run tests/integration"
+    "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"
   },
   "keywords": [
     "llm",