mcp-context-cost 0.9.0 → 0.10.0

package/README.md

@@ -193,9 +193,26 @@ still match today and silence for the rest. Most installs will show a mix:
   memory                   9   2,378    4.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,150 measured tools:
+
+```
+  suggest — descriptions at or above the 90th percentile of measured tools
+  (baseline 2026-09-03: 1,150 tools across 81 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.
+```
+
+A config where nothing is out of distribution is told that in those words, and a baseline
+that cannot be fetched is a named problem, never a silently skipped check.
+
 Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 `--baseline <report.json>`, `--max-increase N`, `--context N` (default 200,000),
-`--timeout ms`, `--concurrency N`, `--docker`, `--claude`.
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`, `--suggest`.
 
 ## Where the numbers come from
 
@@ -329,7 +346,10 @@ 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. Two
+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
 weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
 sixth of the list on Wednesdays, so every row comes round within six 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

@@ -1,4 +1,5 @@
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline, type ToolSuggestion } from '../core/tool-shape.js';
 import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
 import type { ConfiguredServer, LoadedConfig } from './config.js';
 import { type DeferralVerdict, type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
@@ -43,6 +44,19 @@ export interface TrimAdvice {
     recoverableTokens: number;
     recoverableShare: number;
 }
+/**
+ * `--suggest`: this config's tools placed in the measured set's tool-shape
+ * distribution. Only descriptions draw advice (schemas are functional surface;
+ * descriptions are prose every request carries), and only descriptions the
+ * baseline puts at or above the threshold percentile — a config where nothing
+ * is measurably unusual gets that said in those words, not advice invented to
+ * have some.
+ */
+export interface ConfigSuggestions {
+    /** Heaviest-recovery first. */
+    outOfDistribution: ToolSuggestion[];
+    checkedTools: number;
+}
 export interface AuditConfigResult {
     client: string;
     source: string;
@@ -54,6 +68,8 @@ export interface AuditConfigResult {
     skipped: AuditServerResult[];
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
+    /** Present only when `--suggest` ran with a usable baseline. */
+    suggestions?: ConfigSuggestions;
     /**
      * 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.
@@ -128,6 +144,12 @@ export interface AuditReport {
         model: string;
         measuredAt: string;
     };
+    /** Which published tool-shape baseline `--suggest` read its percentiles from. */
+    toolShape?: {
+        generatedAt: string;
+        toolCount: number;
+        serverCount: number;
+    };
     /** Present only when a baseline report was supplied (`--baseline`). */
     diff?: AuditDiff;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
@@ -160,6 +182,8 @@ export declare function buildReport(configs: LoadedConfig[], measured: Map<strin
     generatedAt?: string;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
     divergence?: DivergenceRun | null;
+    /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
+    toolShape?: ToolShapeBaseline | null;
     /**
      * 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

package/dist/audit/audit.js

@@ -14,10 +14,21 @@
  */
 import { METHODOLOGY_VERSION } from '../core/canonical.js';
 import { isCurrent } from '../core/divergence.js';
+import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.js';
 import { evaluateDeferral, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
+function buildSuggestions(pool, baseline) {
+    const outOfDistribution = [];
+    for (const { server, t } of pool) {
+        const s = suggestFor(server, t, baseline);
+        if (s)
+            outOfDistribution.push(s);
+    }
+    outOfDistribution.sort((a, b) => b.approxRecoverableTokens - a.approxRecoverableTokens);
+    return { outOfDistribution, checkedTools: pool.length };
+}
 function buildTrimAdvice(sortedTools, totalTokens) {
     if (totalTokens <= 0 || sortedTools.length < 2)
         return null;
@@ -189,6 +200,7 @@ export function buildReport(configs, measured, opts = {}) {
         const ok = [];
         const skipped = [];
         const tools = [];
+        const shapePool = [];
         // Counted only for servers that put a number into the total: a twin that
         // failed to launch is already a floor, and adds nothing to a sum.
         let sharedHere = 0;
@@ -240,8 +252,11 @@ export function buildReport(configs, measured, opts = {}) {
                 claudeTokens: opts.divergence ? (isCurrent(divRow, m.canonicalSha256 ?? null) ? divRow.claudeDelta : null) : undefined,
                 notes: m.status === 'dynamic' ? m.notes : undefined,
             });
-            for (const t of m.tools)
+            for (const t of m.tools) {
                 tools.push({ server: s.name, tool: t.name, tokens: t.tokens });
+                if (opts.toolShape)
+                    shapePool.push({ server: s.name, t });
+            }
         }
         const totalTokens = ok.reduce((a, s) => a + (s.tokens ?? 0), 0);
         const toolCount = ok.reduce((a, s) => a + (s.toolCount ?? 0), 0);
@@ -264,6 +279,7 @@ export function buildReport(configs, measured, opts = {}) {
             skipped,
             heaviestTools: tools.slice(0, 5),
             trimAdvice: buildTrimAdvice(tools, totalTokens),
+            suggestions: opts.toolShape ? buildSuggestions(shapePool, opts.toolShape) : undefined,
         };
         built.push(result);
         shared.set(result, sharedHere);
@@ -282,6 +298,13 @@ export function buildReport(configs, measured, opts = {}) {
     if (opts.divergence) {
         report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
     }
+    if (opts.toolShape) {
+        report.toolShape = {
+            generatedAt: opts.toolShape.generatedAt,
+            toolCount: opts.toolShape.toolCount,
+            serverCount: opts.toolShape.serverCount,
+        };
+    }
     if (typeof opts.budget === 'number') {
         // The worst config is the gate: passing because your *lightest* client fits
         // would be a green check on a session you don't run.
@@ -617,6 +640,35 @@ export function formatReport(report) {
                 `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
                 `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
         }
+        if (cfg.suggestions) {
+            const sg = cfg.suggestions;
+            const base = report.toolShape
+                ? `baseline ${report.toolShape.generatedAt}: ${n(report.toolShape.toolCount)} tools across ` +
+                    `${report.toolShape.serverCount} measured servers`
+                : 'published baseline';
+            lines.push('');
+            if (sg.outOfDistribution.length === 0) {
+                lines.push(`  suggest: every description in this config sits inside the measured distribution — ` +
+                    `nothing the data can point at (${sg.checkedTools} tools against ${base}).`);
+            }
+            else {
+                lines.push(`  suggest — descriptions at or above the ${SUGGEST_DESCRIPTION_PERCENTILE}th percentile of ` +
+                    `measured tools (${base}):`);
+                const shown = sg.outOfDistribution.slice(0, 8);
+                for (const s of shown) {
+                    lines.push(`    ${s.server} · ${s.tool} — ${n(s.tokens)} tokens: description ${n(s.descriptionTokens)} ` +
+                        `(p${s.descriptionPercentile}), schema ${n(s.inputSchemaTokens)}`);
+                    lines.push(`      rewriting the description toward the measured median (${n(s.medianDescriptionTokens)}) ` +
+                        `would recover ≈${n(s.approxRecoverableTokens)} tokens on every request`);
+                }
+                if (sg.outOfDistribution.length > shown.length) {
+                    lines.push(`    …and ${sg.outOfDistribution.length - shown.length} more above the threshold.`);
+                }
+                const within = sg.checkedTools - sg.outOfDistribution.length;
+                lines.push(`    ${within} of ${sg.checkedTools} tools sit inside the distribution — ` +
+                    `no advice where nothing is measurably unusual.`);
+            }
+        }
         if (cfg.skipped.length) {
             lines.push('');
             lines.push('  not measured');

package/dist/audit/run.d.ts

@@ -1,10 +1,13 @@
 import type { Measurement } from '../core/types.js';
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline } from '../core/tool-shape.js';
 import { type AuditReport } from './audit.js';
 import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type LoadedConfig } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export declare const DEFAULT_TOOL_SHAPE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json";
 export interface AuditOptions {
     /** Explicit config path(s); when empty, every known client location is tried. */
     configPaths?: string[];
@@ -19,6 +22,10 @@ export interface AuditOptions {
     claude?: boolean;
     /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
     divergenceUrl?: string;
+    /** Place this config's tools in the published tool-shape distribution and advise where the data can. */
+    suggest?: boolean;
+    /** Override the tool-shape.json source — mainly for tests and self-hosted mirrors. */
+    toolShapeUrl?: string;
     /**
      * The tool-search variables as this process's SHELL has them. Defaults to
      * this process's environment. Overridable so a test can state a machine
@@ -33,6 +40,11 @@ export interface AuditOptions {
     settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchToolShape(url: string): Promise<{
+    baseline: ToolShapeBaseline | null;
+    problem?: string;
+}>;
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
 export declare function fetchDivergence(url: string): Promise<{
     run: DivergenceRun | null;

package/dist/audit/run.js

@@ -7,11 +7,27 @@
 import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
+import { parseToolShapeBaseline } from '../core/tool-shape.js';
 import { buildReport, serverKey } from './audit.js';
 import { toolSearchEnv } from './deferral.js';
 import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export const DEFAULT_TOOL_SHAPE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json';
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export async function fetchToolShape(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { baseline: null, problem: `tool shape: HTTP ${res.status} fetching ${url}` };
+        const baseline = parseToolShapeBaseline(await res.text());
+        return baseline ? { baseline } : { baseline: null, problem: `tool shape: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { baseline: null, problem: `tool shape: failed to fetch ${url}: ${e.message}` };
+    }
+}
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
 export async function fetchDivergence(url) {
     try {
@@ -89,14 +105,24 @@ export async function runAudit(opts = {}) {
         divergence = fetched.run;
         divergenceProblem = fetched.problem;
     }
+    let toolShape = null;
+    let toolShapeProblem;
+    if (opts.suggest) {
+        const fetched = await fetchToolShape(opts.toolShapeUrl ?? DEFAULT_TOOL_SHAPE_URL);
+        toolShape = fetched.baseline;
+        toolShapeProblem = fetched.problem;
+    }
     const report = buildReport(configs, measured, {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
+        toolShape,
         env: opts.env ?? toolSearchEnv(process.env),
         settings: opts.settings ?? discoverSettings(opts),
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);
+    if (toolShapeProblem)
+        report.problems.push(toolShapeProblem);
     return report;
 }

package/dist/cli.js

@@ -99,8 +99,8 @@ function rejectUnknownFlags(cmd, argv, spec) {
 const [, , cmd, ...rest] = process.argv;
 if (cmd === 'audit') {
     rejectUnknownFlags('audit', rest, {
-        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url'],
-        boolean: ['json', 'docker', 'claude'],
+        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url', 'tool-shape-url'],
+        boolean: ['json', 'docker', 'claude', 'suggest'],
     });
     const argOf = (name) => {
         const i = rest.indexOf(`--${name}`);
@@ -171,6 +171,8 @@ if (cmd === 'audit') {
             docker: rest.includes('--docker'),
             claude: rest.includes('--claude'),
             divergenceUrl: argOf('divergence-url'),
+            suggest: rest.includes('--suggest'),
+            toolShapeUrl: argOf('tool-shape-url'),
             // Progress goes to stderr so `--json` stdout stays a single parseable object.
             onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
         });

package/dist/core/tool-shape.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Tool shape — where a tool's tokens actually are, and when that is worth
+ * saying anything about.
+ *
+ * Every published measurement already splits each tool into whole /
+ * description / input-schema token counts. This module turns the measured
+ * set's split into a baseline — a quantile table over every measured tool —
+ * so that `audit --suggest` can say something no lone number can: whether a
+ * tool's description is *unusually* heavy, against the population of tools
+ * people actually ship, and roughly what trimming it toward normal would
+ * recover.
+ *
+ * Two disciplines, both this project's usual ones. Advice is only ever about
+ * descriptions: a schema is functional surface and trimming it changes what
+ * the tool can do, while a description is prose about the tool and trimming
+ * it changes only how much every request pays to carry it. And advice is only
+ * given where the data can point at something: a tool inside the measured
+ * distribution gets silence, said in those words, not a suggestion invented
+ * to have one. The threshold is a named constant, the baseline is a dated,
+ * re-derivable artifact regenerated from the same published measurements as
+ * everything else, and the recovery figure is marked approximate because
+ * token boundaries make component counts sum only approximately.
+ *
+ * Versioned independently of the o200k methodology, like every column before
+ * it: `tool-shape/v1` adds an advisory reading and moves no `totalTokens` and
+ * no canonical hash.
+ */
+import type { ToolMeasurement } from './types.js';
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const TOOL_SHAPE_METHOD = "tool-shape/v1";
+/**
+ * A description earns a suggestion only at or above this percentile of the
+ * measured distribution. 90 keeps advice rare and confident: nine of ten
+ * measured tools are "normal" by construction, and the advice names the exact
+ * percentile it fired at rather than hiding behind the threshold.
+ */
+export declare const SUGGEST_DESCRIPTION_PERCENTILE = 90;
+export interface ToolShapeBaseline {
+    method: string;
+    methodologyVersion: string;
+    /** UTC day the baseline was derived (YYYY-MM-DD). */
+    generatedAt: string;
+    /** How many measured servers and tools the quantiles were derived from. */
+    serverCount: number;
+    toolCount: number;
+    /**
+     * Nearest-rank quantile tables, 101 values each (q[0] = min … q[100] = max),
+     * in o200k tokens. Published whole so a reader can re-derive any percentile
+     * claim from the same table the tool used.
+     */
+    quantiles: {
+        tokens: number[];
+        descriptionTokens: number[];
+        inputSchemaTokens: number[];
+    };
+}
+/** Nearest-rank quantile table over `values` — same rank rule as the badge-band percentiles. */
+export declare function quantileTable(values: number[]): number[];
+/**
+ * The largest percentile whose quantile does not exceed `value` — read
+ * directly off the published table, so "heavier than P% of measured tools" is
+ * checkable by anyone holding the same JSON.
+ */
+export declare function percentileOf(quantiles: number[], value: number): number;
+export declare function buildToolShapeBaseline(tools: ToolMeasurement[], meta: {
+    serverCount: number;
+    generatedAt?: string;
+    methodologyVersion: string;
+}): ToolShapeBaseline;
+export declare function parseToolShapeBaseline(text: string): ToolShapeBaseline | null;
+export interface ToolSuggestion {
+    server: string;
+    tool: string;
+    tokens: number;
+    descriptionTokens: number;
+    inputSchemaTokens: number;
+    /** Where this description sits in the measured distribution (0–100). */
+    descriptionPercentile: number;
+    /** The measured set's median description, the "normal" being suggested toward. */
+    medianDescriptionTokens: number;
+    /**
+     * ≈ descriptionTokens − median. Approximate by construction: component
+     * counts do not sum exactly to the whole, and a rewritten description
+     * tokenizes as itself, not as an arithmetic difference.
+     */
+    approxRecoverableTokens: number;
+}
+/**
+ * The suggestion for one tool, or null — null is the common and correct case.
+ * Null when the measurement predates component counts, when the description
+ * sits below the threshold percentile, or when trimming toward the median
+ * would recover nothing.
+ */
+export declare function suggestFor(server: string, t: ToolMeasurement, baseline: ToolShapeBaseline): ToolSuggestion | null;

package/dist/core/tool-shape.js

@@ -0,0 +1,106 @@
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export const TOOL_SHAPE_METHOD = 'tool-shape/v1';
+/**
+ * A description earns a suggestion only at or above this percentile of the
+ * measured distribution. 90 keeps advice rare and confident: nine of ten
+ * measured tools are "normal" by construction, and the advice names the exact
+ * percentile it fired at rather than hiding behind the threshold.
+ */
+export const SUGGEST_DESCRIPTION_PERCENTILE = 90;
+/** Nearest-rank quantile table over `values` — same rank rule as the badge-band percentiles. */
+export function quantileTable(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    const q = [];
+    for (let p = 0; p <= 100; p++) {
+        q.push(p === 0 ? sorted[0] : sorted[Math.min(n - 1, Math.max(0, Math.ceil((p / 100) * n) - 1))]);
+    }
+    return q;
+}
+/**
+ * The largest percentile whose quantile does not exceed `value` — read
+ * directly off the published table, so "heavier than P% of measured tools" is
+ * checkable by anyone holding the same JSON.
+ */
+export function percentileOf(quantiles, value) {
+    let p = 0;
+    for (let i = 0; i <= 100; i++) {
+        if (quantiles[i] <= value)
+            p = i;
+        else
+            break;
+    }
+    return p;
+}
+/** A tool whose measurement carries all three counts — the only kind a baseline may be built from. */
+function complete(t) {
+    return (typeof t.tokens === 'number' && typeof t.descriptionTokens === 'number' && typeof t.inputSchemaTokens === 'number');
+}
+export function buildToolShapeBaseline(tools, meta) {
+    const usable = tools.filter(complete);
+    if (usable.length < 2)
+        throw new Error('fewer than two complete tool measurements — no distribution to derive');
+    return {
+        method: TOOL_SHAPE_METHOD,
+        methodologyVersion: meta.methodologyVersion,
+        generatedAt: meta.generatedAt ?? new Date().toISOString().slice(0, 10),
+        serverCount: meta.serverCount,
+        toolCount: usable.length,
+        quantiles: {
+            tokens: quantileTable(usable.map((t) => t.tokens)),
+            descriptionTokens: quantileTable(usable.map((t) => t.descriptionTokens)),
+            inputSchemaTokens: quantileTable(usable.map((t) => t.inputSchemaTokens)),
+        },
+    };
+}
+export function parseToolShapeBaseline(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const b = parsed;
+    if (!b || typeof b.generatedAt !== 'string' || typeof b.toolCount !== 'number')
+        return null;
+    const q = b.quantiles;
+    const table = (v) => Array.isArray(v) && v.length === 101 && v.every((x) => typeof x === 'number');
+    if (!q || !table(q.tokens) || !table(q.descriptionTokens) || !table(q.inputSchemaTokens))
+        return null;
+    return {
+        method: typeof b.method === 'string' ? b.method : TOOL_SHAPE_METHOD,
+        methodologyVersion: typeof b.methodologyVersion === 'string' ? b.methodologyVersion : 'unknown',
+        generatedAt: b.generatedAt,
+        serverCount: typeof b.serverCount === 'number' ? b.serverCount : 0,
+        toolCount: b.toolCount,
+        quantiles: { tokens: q.tokens, descriptionTokens: q.descriptionTokens, inputSchemaTokens: q.inputSchemaTokens },
+    };
+}
+/**
+ * The suggestion for one tool, or null — null is the common and correct case.
+ * Null when the measurement predates component counts, when the description
+ * sits below the threshold percentile, or when trimming toward the median
+ * would recover nothing.
+ */
+export function suggestFor(server, t, baseline) {
+    if (!complete(t))
+        return null;
+    const pct = percentileOf(baseline.quantiles.descriptionTokens, t.descriptionTokens);
+    if (pct < SUGGEST_DESCRIPTION_PERCENTILE)
+        return null;
+    const median = baseline.quantiles.descriptionTokens[50];
+    const approx = t.descriptionTokens - median;
+    if (approx <= 0)
+        return null;
+    return {
+        server,
+        tool: t.name,
+        tokens: t.tokens,
+        descriptionTokens: t.descriptionTokens,
+        inputSchemaTokens: t.inputSchemaTokens,
+        descriptionPercentile: pct,
+        medianDescriptionTokens: median,
+        approxRecoverableTokens: approx,
+    };
+}

package/dist/sweep/regen.js

@@ -6,6 +6,7 @@ import { appendHistory } from './history.js';
 import { writeServerPages } from './server-pages.js';
 import { writeDashboard } from './dashboard.js';
 import { applyPublishedStats } from './published-stats.js';
+import { writeToolShapeBaseline } from './tool-shape.js';
 const doc = parse(readFileSync('servers.yaml', 'utf8'));
 writeLeaderboard(doc.servers);
 // History first: the server pages read history.csv for their over-time table.
@@ -14,6 +15,10 @@ const p = writeServerPages(doc.servers);
 // The dashboard reads the same results/ and history.csv as the pages do, so it
 // belongs in the same refresh — see writeDashboard's note on why it wasn't.
 const d = writeDashboard();
+// The tool-shape baseline is a quantile table over every measured tool — the
+// distribution `audit --suggest` reads percentile claims from. Derived from
+// the same measurement files as the leaderboard, in the same refresh.
+const ts = writeToolShapeBaseline(doc.servers);
 // The front pages state numbers the sweep just changed; they are patched from
 // the same results/ the leaderboard was. A missing anchor is a page regen can
 // no longer maintain — refuse loudly rather than leave one number stale.
@@ -27,6 +32,7 @@ console.log('leaderboard:', JSON.stringify(percentiles(doc.servers)));
 console.log(`history: ${h.rows} rows (${h.added >= 0 ? '+' : ''}${h.added})`);
 console.log(`server pages: ${p.pages}`);
 console.log(`dashboard: ${d.out} (${(d.bytes / 1024).toFixed(0)}KB)`);
+console.log(`tool shape: ${ts.toolCount} tools across ${ts.serverCount} servers (median description ${ts.quantiles.descriptionTokens[50]})`);
 console.log(`published stats: ${stats.changedFiles.length > 0
     ? `updated ${stats.updated.join(', ')} in ${stats.changedFiles.join(', ')}`
     : 'pages already agree with the data'}`);

package/dist/sweep/tool-shape.d.ts

@@ -0,0 +1,3 @@
+import { type ToolShapeBaseline } from '../core/tool-shape.js';
+import { type ServerEntry } from './report.js';
+export declare function writeToolShapeBaseline(entries: ServerEntry[], root?: string): ToolShapeBaseline;

package/dist/sweep/tool-shape.js

@@ -0,0 +1,26 @@
+/**
+ * Derive the tool-shape baseline from what is on disk and publish it beside
+ * the other generated artifacts. Re-derivable by anyone from the same
+ * measurement files; regenerated on every regen, so it moves with the data it
+ * describes and never sits stale beside a fresh sweep.
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { METHODOLOGY_VERSION } from '../core/canonical.js';
+import { buildToolShapeBaseline } from '../core/tool-shape.js';
+import { loadRows } from './report.js';
+export function writeToolShapeBaseline(entries, root = process.cwd()) {
+    const tools = [];
+    let serverCount = 0;
+    for (const r of loadRows(entries, root)) {
+        if (!r.m || (r.m.status !== 'measured' && r.m.status !== 'dynamic'))
+            continue;
+        if (r.m.tools.length === 0)
+            continue;
+        serverCount++;
+        tools.push(...r.m.tools);
+    }
+    const baseline = buildToolShapeBaseline(tools, { serverCount, methodologyVersion: METHODOLOGY_VERSION });
+    writeFileSync(join(root, 'results', 'tool-shape.json'), JSON.stringify(baseline, null, 2) + '\n');
+    return baseline;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",