mcp-context-cost 0.17.0 → 0.19.0

package/README.md

@@ -4,9 +4,9 @@
 [![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
 [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-MCP%20context%20cost-blue?logo=github)](https://github.com/marketplace/actions/mcp-context-cost)
 
-Two entry points: `audit`, for the config you run (below), and a GitHub Action, for the
-server you publish — five lines in a workflow that fail a pull request adding more context
-cost than you meant to ship:
+Three entry points: `audit`, for the config you run (below); a GitHub Action, for the server
+you publish; and the measurement itself, as a library, for anything else. The Action is five
+lines in a workflow that fail a pull request adding more context cost than you meant to ship:
 
 ```yaml
 - uses: athakur3/mcp-context-cost@v1
@@ -24,12 +24,28 @@ gate passed or not, so a later step can comment the number on the PR or publish
 [how the gate decides](#defend-the-number-dont-just-display-it) ·
 [what the number is](docs/METHODOLOGY.md).
 
+As a library, if you want the measurement without either wrapper — the same canonical form,
+the same tokenizer, the same badge:
+
+```js
+import { measureTools, canonicalString, toBadge, METHODOLOGY_VERSION } from "mcp-context-cost";
+```
+
+It is the definition rather than the harness: measurement and canonical bytes, the color
+bands, the badge JSON, the Claude field-selection mapping, and the session-start load. It
+does not launch servers or read your config — that is what `audit` is for. The surface is
+pinned by a test, so a name is added or removed on purpose and says so in the changelog.
+
 **What do the MCP servers in your config cost you before you type anything — and what did
 that last config change add to every session you will ever run?**
 
-Every MCP server you wire into an agent injects its tool schemas into the model's context on
-every single request. You pay that whether or not the agent ends up using the tools, and no
-client shows you the number. Point `audit` at your own MCP config:
+Every MCP server you wire into an agent has to put its tool schemas somewhere. For a client
+with no deferral on record that is the model's context, on every single request, whether or
+not the agent ends up using the tools; for a client that defers them — Claude Code by default,
+and Cursor, Codex CLI and VS Code by their vendors' own records — it is a smaller session-start
+cost plus whatever the agent reaches for. Which of the two you are paying is a property of your
+client, not of the server, and no client shows you either number. Point `audit` at your own MCP
+config:
 
 ```bash
 npx -y mcp-context-cost audit
@@ -65,16 +81,15 @@ VS Code (`.vscode/mcp.json`), Windsurf, Codex CLI (`~/.codex/config.toml`), Gemi
 Goose (`~/.config/goose/config.yaml`) — or pass `--config <path>`. Servers are measured by
 the same path as the published leaderboard (dual `tools/list` capture, `o200k_base` over
 canonical JSON), so a server in both places gets the same number. Nothing is written to your
-project, and env var **values** are never read into the output — only their names.
+project, and no **value** an entry carries — an env var, a header — is ever read into the
+output. Only their names are.
 
-A remote entry — `url`, or the client's own spelling of it — is first asked what it says to
-an unauthenticated `initialize`. An endpoint that answers is measured through the
-`mcp-remote` bridge, the path the leaderboard's remote rows already take. One that answers
-`401` or `403` is reported **auth-walled**, quoting the status and the `WWW-Authenticate`
-header it sent, with the URL: a working server this audit holds no credential for, so the
-total above it is a floor. One that answers nothing usable is **unreachable**, with the
-reason. Header values an entry carries are sent and never printed — only their names are —
-and nothing here ever opens a browser.
+A remote entry — `url`, or the client's own spelling of it — is probed before anything is
+launched, and reported as measured, **auth-walled** or **unreachable** depending on what it
+answers; an auth-walled row makes the total above it a floor rather than a number. The probe,
+what each verdict quotes, and why it exists at all are in
+[METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays). Nothing here opens a
+browser.
 
 Totals are reported per config file, never merged: a context window belongs to one client
 session, so summing Cursor's servers into Claude Desktop's total would describe a session
@@ -83,33 +98,19 @@ nobody runs.
 ### Where this cost is paid in full, and where it is deferred away
 
 Not every client puts every tool definition in context on every request, so the total above
-is not automatically your bill. Which client reads the config, and how that client is
-configured **on this machine**, decides it — and `audit` reads that rather than assuming it.
-
-**Clients with no default deferral on record** — Claude Desktop, Cursor, VS Code, Windsurf,
-Codex CLI, Gemini CLI, Zed, Kiro, Goose. The total is what every request carries, as in the
-example above. That sentence is an
-absence of a record about those clients, not a measurement of them, and the report says so
-in those words.
-
-**Claude Code defers MCP tool definitions by default** (its **tool search**): they are not
-in context at session start, and load when the model reaches for one. Three variables move
-that, and `audit` reads all three — from the shell it runs in *and* from the `env` block of
-Claude Code's own settings files (managed, `<cwd>/.claude/settings.local.json`,
-`<cwd>/.claude/settings.json`, `~/.claude/settings.json`), because a machine that switched
-deferral off in a settings file is not a machine running the default:
-
-| setting | what the audit reports |
-|---|---|
-| nothing set (the default) | every definition deferred, at any size — no threshold applies |
-| `ENABLE_TOOL_SEARCH=true` | same: every definition deferred |
-| `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total. In a settings `env` block that is the **string** `"false"`; the JSON boolean `false` is the last row, not this one |
-| `ENABLE_TOOL_SEARCH=auto` / `auto:N` | deferred only once definitions reach 10% / N% of the context window |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
-| `ANTHROPIC_BASE_URL` off `api.anthropic.com` | falls back to loading up front — consulted only while `ENABLE_TOOL_SEARCH` is unset |
-| anything else in `ENABLE_TOOL_SEARCH` | not a documented value, so nothing is claimed from it |
-| any of the three set, in a settings `env` block, to something that is not a string — a JSON boolean, a number, `null` | it is set there and what it is set to is unknown, so no posture is claimed: the report says whether these tokens are deferred cannot be said from it |
-| a server pinned `"alwaysLoad": true` in its entry | loads at session start whatever the setting says — read from the entry, named with its tokens, and left out of any threshold comparison |
+is not automatically your bill. Which client reads the config decides it, and for Claude Code
+so does how that client is configured **on this machine** — three environment variables and a
+per-server `alwaysLoad` pin, which `audit` reads rather than assumes, from the shell it runs
+in *and* from the `env` block of Claude Code's own settings files. No other client's posture
+is readable from a file this opens, so for those the report gives what the vendor is on record
+with, or says there is nothing on record, and claims neither as a measurement.
+
+**The model is written down once, on the methodology page**, because it gets corrected often
+and a second copy here would be a second place to correct:
+[METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays) carries every variable and
+what it resolves to, the four kinds of first-party record the rule admits, the questions the
+report refuses to answer rather than guess, and the address and date behind every claim. What
+follows is what that model looks like when you run it.
 
 On a machine where none of them is set, the same stack reads:
 
@@ -130,7 +131,7 @@ On a machine where none of them is set, the same stack reads:
     a tool whose _meta carries "anthropic/alwaysLoad": true, which this audit does not read from a capture
 ```
 
-**Do not take that table on trust — your own client will tell you.** Everything above is read
+**Do not take that model on trust — your own client will tell you.** All of it is read
 from Anthropic's documentation, and documentation about someone else's product is exactly the
 kind of claim this project refuses to leave unchecked elsewhere. Claude Code writes its own
 decision to a debug log, before it sends anything, so you can check your machine rather than
@@ -147,7 +148,7 @@ Three line shapes answer three different questions:
 |---|---|
 | `[ToolSearch:optimistic] mode=…, ENABLE_TOOL_SEARCH=…, result=…` | which mode it picked at startup, and the value it read. **Optimistic is its own word for a guess** — it can be revised below |
 | `Dynamic tool loading: 0/N deferred tools included` | the one that settles it: how many of the `N` deferrable tools went into the request. `0/N` is deferral actually happening |
-| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the fallback in the table above, firing, in the client's own words |
+| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the base-URL fallback, firing, in the client's own words |
 
 Read the *later* requests, not the first. A stdio server can finish connecting after the first
 request has already gone, so an early low count is a race rather than a finding.
@@ -160,9 +161,10 @@ a proportionally larger one — pass `--context` to `audit` to compare against t
 actually run.
 
 None of this is free, and it is one trivial request. These are Claude Code's own debug lines
-rather than a documented interface, so they can change; the table above is what this project
-holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
-which is why their rows say an absence of a record rather than a measurement.
+rather than a documented interface, so they can change; the methodology page is what this
+project holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
+which is why no other row here is a measurement: three of them get their vendor's own record,
+dated and addressed, and the rest an absence of one.
 
 Set `ENABLE_TOOL_SEARCH=false` in that shell and the same config reports the opposite —
 `loads every tool definition up front here`, naming the variable and the place it was read
@@ -171,20 +173,6 @@ tool names plus the server's `instructions` — is measured per server and publi
 leaderboard's `session start` column, and for at least one server in the published set it
 costs **more** than loading the definitions would.
 
-Three things the report will not do: it will not convert between units silently (in
-threshold mode the stack is compared as a range, because the audit counts wire bytes and the
-threshold is counted in what the client sends to the API — measured at 0.19×–1.93× across 86
-servers); it will not claim a posture the machine did not state readably, which is four
-refusals and not one — when two places set the same variable to different values, when a
-settings file exists and cannot be read, when the place that would decide sets the variable
-to something that is not a string, and when `ENABLE_TOOL_SEARCH` holds a value Claude Code
-does not document; and it will not pass an absence of a record off as a measurement. The
-first two print as unanswered questions. The third prints as an answer that names
-itself: for the nine discovered clients with no default on record — `claude-desktop`, `cursor`, `vscode`, `windsurf`, `codex`, `gemini`, `zed`, `kiro`, `goose` — the tokens are counted as
-loaded up front, and the report says so in those words, "an absence of a record about the
-client, not a measurement of it".
-Full model, sources and dates: [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays).
-
 **In CI**, make it a gate — the bundlesize move for agents:
 
 ```bash
@@ -257,19 +245,18 @@ still match today and silence for the rest. Most installs will show a mix:
 
 ```
   server               tools  tokens   share   claude
-  github                  44  54,422   95.8%   18,406
-  memory                   9   2,378    4.2%       —
+  my-server               18   9,400   79.8%    3,120
+  my-fork                  6   2,380   20.2%       —
 ```
 
-Add `--suggest` to place each of your tools in the measured set's tool-shape distribution
-([method](docs/METHODOLOGY.md#tool-shape)) and get advice only where the data can point at
-something. Only descriptions draw advice — schemas are functional surface; descriptions are
-prose every request carries — and only descriptions at or above the 90th percentile of the
-1,430 measured tools:
+Add `--suggest` to place each of your tools in the measured set's tool-shape distribution and
+get advice only where the data can point at something. What draws a suggestion, what never
+does, and the percentile that decides are in
+[METHODOLOGY §tool shape](docs/METHODOLOGY.md#tool-shape):
 
 ```
   suggest — descriptions at or above the 90th percentile of measured tools
-  (baseline 2026-09-05: 1,430 tools across 87 measured servers):
+  (baseline 2026-09-07: 1,430 tools across 87 measured servers):
     stub · wordy — 345 tokens: description 321 (p92), schema 14
       rewriting the description toward the measured median (27) would recover ≈294 tokens on every request
     1 of 2 tools sit inside the distribution — no advice where nothing is measurably unusual.
@@ -285,8 +272,8 @@ are not:
 
 ```
   changed — published versions of your servers that have moved since
-  (index 2026-09-04, 2 published captures; matched by canonical hash, never by name):
-    notes (published as obsidian) — you have the capture published 2026-08-19 at 1,132 tokens;
+  (index 2026-09-05, 99 published captures; matched by canonical hash, never by name):
+    notes (published as my-server) — you have the capture published 2026-08-19 at 1,132 tokens;
       the current one is 2,062 (+930, 2026-08-26)
     updating all 1 would add 930 tokens to every request in this client.
 ```
@@ -303,20 +290,21 @@ Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 
 The number `audit` gives you is the same measurement, run across a curated set of public
 servers — which is how you can tell it is a measurement and not this tool's opinion. It also
-shows what you are choosing between: across the 87 servers measured, cost spans **1,700×**,
-from `postgres` at 32 tokens to `github` at 54,622. The table below is a
-sample of that range; the full range is in
+shows what you are choosing between: across the 87 servers measured, cost spans **1,700×** on
+the wire, from `postgres` at 32 tokens to `github` at 54,622 — of which a request carries
+10,735, and Claude counts those at 18,728. The table below is a sample of that range, ranked
+on the wire like every other list here; the full range is in
 [results/leaderboard.md](results/leaderboard.md).
 
-| server | context cost | tools |
-|---|---:|---:|
-| github (official) | **54,622 tokens** | 44 |
-| xcodebuildmcp | 26,594 | 24 |
-| brave-search | 25,487 | 8 |
-| notion | 17,500 | 24 |
-| playwright *(4.8M installs/week)* | 4,024 | 24 |
-| filesystem (reference) | 2,823 | 14 |
-| markitdown | 64 | 1 |
+| server | context cost (wire) | mapped | on Claude | tools |
+|---|---:|---:|---:|---:|
+| github (official) | **54,622 tokens** | 10,735 | 18,728 | 44 |
+| xcodebuildmcp | 26,594 | 2,676 | 5,335 | 24 |
+| brave-search | 25,487 | 8,278 | 13,762 | 8 |
+| notion | 17,500 | 17,163 | 33,560 | 24 |
+| playwright *(4.8M installs/week)* | 4,024 | 3,402 | 6,172 | 24 |
+| filesystem (reference) | 2,823 | 1,665 | 3,115 | 14 |
+| markitdown | 64 | 64 | 404 | 1 |
 
 *(87 of 107 popular servers measured, each row dated by its own most recent sweep — full table in
 [results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
@@ -342,12 +330,14 @@ the cost before they install rather than after:
 
 The badge counts every byte a server returns. An Anthropic request carries only `name`,
 `description`, and `input_schema` — and counts them with a denser tokenizer. Both effects are
-now measured against a pinned model and published beside the badge, and they do not cancel:
+now measured against a pinned model and published beside the badge, and they do not cancel.
+The middle column is what a request actually carries, counted with the badge's own tokenizer,
+so the two effects are separated rather than folded together:
 
-| server | badge (o200k) | Claude (`claude-opus-5`) | |
-|---|---:|---:|---|
-| github | 54,622 | **18,728** | 78% of the capture is `icons` metadata Claude never sees |
-| notion | 17,500 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
+| server | badge (o200k) | mapped | Claude (`claude-opus-5`) | |
+|---|---:|---:|---:|---|
+| github | 54,622 | 10,735 | **18,728** | 78% of the capture is `icons` metadata Claude never sees |
+| notion | 17,500 | 17,163 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
 
 So the heaviest server on the badge is not the heaviest server on Claude. Per-server
 breakdowns are on each [detail page](https://athakur3.github.io/mcp-context-cost/servers/);
@@ -355,9 +345,10 @@ the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
 
 ## Why trust the number?
 
-Every published number is backed by a `measurement.json` containing the raw `tools/list`
-capture, the SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the
-exact launch command. Disputes reduce to a byte-level diff:
+Every published number is backed by a `measurement.json`. What it holds, and the five lines
+that re-derive the number from it, are in
+[METHODOLOGY §reproduce it](docs/METHODOLOGY.md#reproduce-it). Disputes reduce to a byte-level
+diff, and the CLI does that for you:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
@@ -395,7 +386,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
 | `tools/` | the scripts that call a network API — the Claude divergence run, the adoption reading, the registry scan — kept out of the package so the library stays offline |
-| `upstream/` | `badge.sh` + composite-action patch + bash tests — the self-serve badge recipe, carried here |
+| `upstream/` | `badge.sh` + bash tests — the self-serve badge recipe, carried here |
 | `servers.yaml` | 107 curated candidates with live install metrics and provenance |
 | `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
 | `docs/` | methodology, dashboard, and a generated page per measured server |
@@ -411,14 +402,12 @@ That prints the number and writes nothing. Published records
 (`results/<name>/measurement.json`, `badges/<name>.json`, the `history.csv`
 row) come from CI: a developer machine is a different architecture under
 different load, and a measurement taken there describes it rather than the
-server. `local-mcp`'s failing record was made on an arm64 laptop, and its
-stderr named an architecture the record itself did not — which is why every
-measurement now records `isolation.arch`. The entry turned out to be
-unavailable on both architectures, and a record that says where it was made
-is what lets that be told from a broken server. To get your server into the
-leaderboard, add an entry to `servers.yaml` and open a pull request; the check
-on that PR measures the entry read-only, and the rotation publishes it after
-merge.
+server. Which machine a number applies to, and the failed record that made it
+a rule, are in
+[METHODOLOGY §which machine a number applies to](docs/METHODOLOGY.md#which-machine-a-number-applies-to).
+To get your server into the leaderboard, add an entry to `servers.yaml` and
+open a pull request; the check on that PR measures the entry read-only, and the
+rotation publishes it after merge.
 
 For a badge on your own README, run the published CLI in your server's own CI
 (the [gate](#defend-the-number-dont-just-display-it) below writes
@@ -446,7 +435,7 @@ cp results/my-server/measurement.json .context-cost/baseline.json
 
 # on every pull request
 npx -y mcp-context-cost measure --name my-server --command "node dist/index.js" \
-  --baseline .context-cost/baseline.json --max-increase 500
+  --baseline .context-cost/baseline.json --max-increase 100
 ```
 
 ```
@@ -460,26 +449,13 @@ INCREASE FAIL: +121 tokens, over the 100 allowed — this change adds that to ev
 
 Both sides are single measurements carrying per-tool counts, so an established
 change is attributed exactly: which tools arrived, which grew, and by how much.
-And `--max-increase` fails on more than the number — a server that stops
-starting on the branch makes the total go *down*, and reporting that as an
-improvement is the one mistake a gate like this must not make, so a change that
-could not be established fails too.
-
-As a GitHub Action, that whole workflow is five lines
-([full example](examples/server-author-ci.yml)):
-
-```yaml
-- uses: athakur3/mcp-context-cost@v1
-  with:
-    name: my-server
-    command: node dist/index.js
-    baseline: .context-cost/baseline.json
-    max-increase: 500
-```
+And `--max-increase` fails on more than the number here too: a change that could
+not be established fails the gate, for the reason the `audit` gate gives above.
 
-It exposes `tokens`, `tools`, `status`, `measurement` and `badge` as outputs —
-available whether the gate passed or not — so a later step can comment the
-number on the pull request or publish the badge.
+As a GitHub Action that whole workflow is the five lines at the top of this page
+([full example](examples/server-author-ci.yml)) — the same inputs, and the same
+outputs written whether the gate passed or not, for a later step to comment on
+the pull request or publish as a badge.
 
 Point the link at the measurement behind the number — for servers in this sweep that is
 `https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
@@ -499,17 +475,14 @@ npx tsc --noEmit                # typecheck
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
 ```
 
-Notable engineering choices: the MCP client is a deliberate ~220-line raw-wire
-implementation (SDK schema-parsing can reorder keys, which would corrupt canonical bytes);
+Notable engineering choices: the MCP client is a deliberate raw-wire implementation
+rather than the SDK (schema-parsing can reorder keys, which would corrupt canonical bytes);
 sweep servers run in credential-free Docker containers with recorded isolation; the badge
 color bands are frozen against the observed distribution of the first full sweep.
 
 ## Status
 
-Active. Every row carries the date of its own most recent measurement, and what the data
-says as a whole is written up, dated, in
-[The State of MCP Context Cost](https://athakur3.github.io/mcp-context-cost/state-of-mcp-context-cost)
-(September 2026). Two
+Active. Every row carries the date of its own most recent measurement. Two
 weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
 third of the list on Wednesdays, so every row comes round within three weeks. Read each row's
 date as the date it means, and don't take the cadence on trust — the build history is

package/dist/audit/audit.d.ts

@@ -25,23 +25,23 @@ export interface AuditServerResult {
     toolCount: number | null;
     /** Share of this config's measured total, 0–1. */
     share: number | null;
-    command?: string;
-    url?: string;
+    command?: string | undefined;
+    url?: string | undefined;
     /** Names only — a server's env values never enter a report. */
     envVarNames: string[];
     /** Names only, and only for a remote entry that carries any — values never enter a report. */
-    headerNames?: string[];
+    headerNames?: string[] | undefined;
     /** Claude Code's `alwaysLoad: true`, read from the entry: loads at session start whatever the setting. */
-    alwaysLoad?: true;
-    canonicalSha256?: string | null;
+    alwaysLoad?: true | undefined;
+    canonicalSha256?: string | null | undefined;
     /**
      * Anthropic-request cost from the published Claude divergence run, only when
      * its captured hash matches this install (`--claude`). `null` means the
      * install doesn't match what was published — silence, not a stale guess.
      * `undefined` means `--claude` wasn't requested at all.
      */
-    claudeTokens?: number | null;
-    notes?: string;
+    claudeTokens?: number | null | undefined;
+    notes?: string | undefined;
 }
 export interface HeaviestTool {
     server: string;
@@ -96,9 +96,9 @@ export interface AuditConfigResult {
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
     /** Present only when `--suggest` ran with a usable baseline. */
-    suggestions?: ConfigSuggestions;
+    suggestions?: ConfigSuggestions | undefined;
     /** Present only when `--changed` ran with a usable capture index. */
-    captureVerdicts?: ServerCaptureVerdict[];
+    captureVerdicts?: ServerCaptureVerdict[] | undefined;
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -171,30 +171,30 @@ export interface AuditReport {
          * against the whole stack and the verdict fails rather than passing on a
          * total that understates by an unknown amount.
          */
-        unestablished?: string[];
+        unestablished?: string[] | undefined;
         /** Present only when over budget: the arithmetic of getting back under it. */
-        fit?: BudgetFit;
+        fit?: BudgetFit | undefined;
     };
     /** Present only when a divergence run was supplied (`--claude`). */
     claudeDivergence?: {
         model: string;
         measuredAt: string;
-    };
+    } | undefined;
     /** Which published tool-shape baseline `--suggest` read its percentiles from. */
     toolShape?: {
         generatedAt: string;
         toolCount: number;
         serverCount: number;
-    };
+    } | undefined;
     /** Which published capture index `--changed` joined against. */
     captureIndex?: {
         generatedAt: string;
         captureCount: number;
-    };
+    } | undefined;
     /** Present only when a baseline report was supplied (`--baseline`). */
-    diff?: AuditDiff;
+    diff?: AuditDiff | undefined;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
-    increaseGate?: IncreaseGate;
+    increaseGate?: IncreaseGate | undefined;
     problems: string[];
 }
 /** Cache key for measurement reuse: the exact argv two configs would spawn. */
@@ -218,38 +218,36 @@ export declare function collapsedKeys(configs: LoadedConfig[]): Set<string>;
  * launching a single server.
  */
 export declare function buildReport(configs: LoadedConfig[], measured: Map<string, Measurement>, opts?: {
-    contextWindow?: number;
-    budget?: number;
-    generatedAt?: string;
+    contextWindow?: number | undefined;
+    budget?: number | undefined;
+    generatedAt?: string | undefined;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
-    divergence?: DivergenceRun | null;
+    divergence?: DivergenceRun | null | undefined;
     /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
-    toolShape?: ToolShapeBaseline | null;
+    toolShape?: ToolShapeBaseline | null | undefined;
     /** Published `capture-index/v1` (`--changed`); omit to skip the version join. */
-    captureIndex?: CaptureIndex | null;
+    captureIndex?: CaptureIndex | null | undefined;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its
      * inputs; `runAudit` supplies the real environment. Omitted means the shell
      * set nothing.
      */
-    env?: ToolSearchEnv;
+    env?: ToolSearchEnv | undefined;
     /**
      * The other place those variables come from: Claude Code's own settings
      * files, highest precedence first, as `loadSettingsSources` read them.
      * `runAudit` supplies these. Omitted means they were not read here — which
      * the report says, rather than reporting a default it did not establish.
      */
-    settings?: ToolSearchSource[];
+    settings?: ToolSearchSource[] | undefined;
     /**
      * What each remote endpoint said to an unauthenticated `initialize`, keyed
      * by `serverKey`. `runAudit` supplies it from `probeRemotes`; omitted, a
      * remote entry is reported as not probed rather than as anything else.
      */
-    remotes?: Map<string, RemoteProbe>;
+    remotes?: Map<string, RemoteProbe> | undefined;
 }): AuditReport;
 /** Human output. JSON output is the report object itself. */
 export declare function formatReport(report: AuditReport): string;
-/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
-export declare function allHeaviestTools(report: AuditReport, limit?: number): HeaviestTool[];
 export type { ToolMeasurement };