efaimo 0.1.2 → 0.3.0

package/dist/rules/version.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Which ruleset produced a report.
+ *
+ * The tool version does not answer this. A patch release can change what a
+ * rule fires on without changing any documented behaviour (0.1.2 did exactly
+ * that: E123 started matching `delete_file`, and every grade that rule touched
+ * moved), so "efaimo 0.1.2 said A(95)" is only reproducible if the reader can
+ * also tell which rules were running. Every JSON envelope now carries this.
+ *
+ * Values:
+ *   "1"  every ruleset through efaimo 0.1.2. Reports from those versions carry
+ *        no `rulesVersion` field at all; the absence IS the value.
+ *   "2"  the first ruleset that declares itself. Adds the findability family
+ *        (E141-E145), which no earlier version had.
+ *
+ * Bump it when a rule is added, removed, renumbered, or changed in what it
+ * fires on. `test/meta.test.ts` pins the rule inventory, so an added or
+ * removed rule cannot land without someone looking at this file. It cannot
+ * detect a changed threshold inside an existing rule: that one is human
+ * discipline, and this comment is where the discipline is written down.
+ *
+ * Deliberately not derived from package.json. Tying it to the release number
+ * would make it move on every release whether or not a rule moved, which is
+ * the thing it exists to distinguish.
+ */
+export declare const RULES_VERSION = "2";

package/dist/rules/version.js

@@ -0,0 +1,26 @@
+/**
+ * Which ruleset produced a report.
+ *
+ * The tool version does not answer this. A patch release can change what a
+ * rule fires on without changing any documented behaviour (0.1.2 did exactly
+ * that: E123 started matching `delete_file`, and every grade that rule touched
+ * moved), so "efaimo 0.1.2 said A(95)" is only reproducible if the reader can
+ * also tell which rules were running. Every JSON envelope now carries this.
+ *
+ * Values:
+ *   "1"  every ruleset through efaimo 0.1.2. Reports from those versions carry
+ *        no `rulesVersion` field at all; the absence IS the value.
+ *   "2"  the first ruleset that declares itself. Adds the findability family
+ *        (E141-E145), which no earlier version had.
+ *
+ * Bump it when a rule is added, removed, renumbered, or changed in what it
+ * fires on. `test/meta.test.ts` pins the rule inventory, so an added or
+ * removed rule cannot land without someone looking at this file. It cannot
+ * detect a changed threshold inside an existing rule: that one is human
+ * discipline, and this comment is where the discipline is written down.
+ *
+ * Deliberately not derived from package.json. Tying it to the release number
+ * would make it move on every release whether or not a rule moved, which is
+ * the thing it exists to distinguish.
+ */
+export const RULES_VERSION = "2";

package/dist/testing/anthropicRunner.d.ts

@@ -1,4 +1,34 @@
 import type { Runner } from "./harness.js";
+/**
+ * Which Claude models still accept `temperature` / `top_p` / `top_k`.
+ *
+ * Sampling parameters were removed from the Claude 4.7 line onward and now
+ * return a 400 on Fable 5, Opus 5, Opus 4.8, Opus 4.7 and Sonnet 5. This
+ * runner used to send `temperature` on every request, and the scenario default
+ * model is `claude-sonnet-5`, so `efaimo test --live` sent a rejected
+ * parameter on its first call; `isTransient()` correctly does not retry a 400,
+ * so the whole scenario threw before a single trial completed.
+ *
+ * Nothing in the suite could see it. The runner is injected precisely so the
+ * A/B logic can be tested without spending tokens, which means every test in
+ * this repo exercises a fake and none of them ever built this request body.
+ * The fix is therefore paired with a test that asserts on the body itself.
+ *
+ * The list is an ALLOWLIST of models that accept the parameter, and it is
+ * closed: it names model lines that already shipped, so it cannot go stale in
+ * the direction that breaks a run. A model released after this was written is
+ * unknown to it and gets no `temperature`, which costs a little determinism on
+ * the judge and cannot cost a 400. The opposite shape - a denylist of models
+ * that reject it - would fail every future release by default.
+ */
+export declare function acceptsSamplingParams(model: string): boolean;
+/** The request body, split out so a test can assert on it without a network call. */
+export declare function anthropicRequestBody(req: {
+    model: string;
+    system?: string;
+    user: string;
+    deterministic?: boolean;
+}): Record<string, unknown>;
 /**
  * The live runner. Used only by `efaimo test --live`, because every call spends
  * tokens on the caller's ANTHROPIC_API_KEY.

package/dist/testing/anthropicRunner.js

@@ -1,3 +1,45 @@
+/**
+ * Which Claude models still accept `temperature` / `top_p` / `top_k`.
+ *
+ * Sampling parameters were removed from the Claude 4.7 line onward and now
+ * return a 400 on Fable 5, Opus 5, Opus 4.8, Opus 4.7 and Sonnet 5. This
+ * runner used to send `temperature` on every request, and the scenario default
+ * model is `claude-sonnet-5`, so `efaimo test --live` sent a rejected
+ * parameter on its first call; `isTransient()` correctly does not retry a 400,
+ * so the whole scenario threw before a single trial completed.
+ *
+ * Nothing in the suite could see it. The runner is injected precisely so the
+ * A/B logic can be tested without spending tokens, which means every test in
+ * this repo exercises a fake and none of them ever built this request body.
+ * The fix is therefore paired with a test that asserts on the body itself.
+ *
+ * The list is an ALLOWLIST of models that accept the parameter, and it is
+ * closed: it names model lines that already shipped, so it cannot go stale in
+ * the direction that breaks a run. A model released after this was written is
+ * unknown to it and gets no `temperature`, which costs a little determinism on
+ * the judge and cannot cost a 400. The opposite shape - a denylist of models
+ * that reject it - would fail every future release by default.
+ */
+export function acceptsSamplingParams(model) {
+    return /^claude-(3|(sonnet|haiku|opus)-4-5|(opus|sonnet)-4-6)\b/i.test(model);
+}
+/** The request body, split out so a test can assert on it without a network call. */
+export function anthropicRequestBody(req) {
+    const body = {
+        model: req.model,
+        max_tokens: 1024,
+        ...(req.system ? { system: req.system } : {}),
+        messages: [{ role: "user", content: req.user }],
+    };
+    // 0 for the judge, 1 for the subject (see RunnerRequest.deterministic), but
+    // only where the model still has the parameter. Where it does not, the
+    // subject arm is unaffected (1 was the default anyway) and the judge simply
+    // is not pinned; `runScenario` is told so it can say it in the report,
+    // because an unpinned judge is variance that lands in the measurement.
+    if (acceptsSamplingParams(req.model))
+        body.temperature = req.deterministic ? 0 : 1;
+    return body;
+}
 /**
  * The live runner. Used only by `efaimo test --live`, because every call spends
  * tokens on the caller's ANTHROPIC_API_KEY.
@@ -11,14 +53,7 @@ export function anthropicRunner(apiKey) {
                 "x-api-key": apiKey,
                 "anthropic-version": "2023-06-01",
             },
-            body: JSON.stringify({
-                model: req.model,
-                // 0 for the judge, 1 for the subject. See RunnerRequest.deterministic.
-                temperature: req.deterministic ? 0 : 1,
-                max_tokens: 1024,
-                ...(req.system ? { system: req.system } : {}),
-                messages: [{ role: "user", content: req.user }],
-            }),
+            body: JSON.stringify(anthropicRequestBody(req)),
             redirect: "error",
             signal: AbortSignal.timeout(60000),
         });

package/dist/testing/harness.d.ts

@@ -10,6 +10,24 @@ export interface Scenario {
     skillName: string;
     skillBody: string;
     model: string;
+    /**
+     * The model that grades the attempts. Defaults to `model`, which is what it
+     * always was, and that default is a known confound: a model grading its own
+     * output prefers it, so an effect measured that way is partly a measurement
+     * of self-preference. Set it to a different model (`judge_model:` in the
+     * scenario, or `--judge-model`) and the report prints both.
+     */
+    judgeModel: string;
+    /**
+     * Whether `judge_model:` was written in the scenario.
+     *
+     * `--model` moves the judge with the subject only when the judge was never
+     * pinned. Without this flag the two cases are indistinguishable: a scenario
+     * that deliberately pins `judge_model` to the same id as `model` looked
+     * identical to one that omitted the key, so `--model gpt-4o-mini` would have
+     * moved a deliberately pinned judge.
+     */
+    judgeModelExplicit: boolean;
     trials: number;
     task: string;
     judge: string;
@@ -43,12 +61,23 @@ export interface TestReport {
     scenario: string;
     skill: string;
     model: string;
+    judgeModel: string;
     withSkill: ArmResult;
     withoutSkill: ArmResult;
     /** withSkill.passRate - withoutSkill.passRate, in percentage points. */
     deltaPoints: number;
     /** Two-sided Fisher exact p on the 2x2 of scored trials. */
     p: number;
+    /**
+     * Two-sided Fisher exact p on the 2x2 of UNPARSEABLE trials.
+     *
+     * Dropping a trial the judge did not answer is only unbiased if the dropping
+     * is unrelated to which arm produced it. If one arm loses materially more
+     * trials than the other, the surviving denominators are not comparable and
+     * the delta is measuring the judge as much as the skill. Low p here means
+     * the exclusions are skewed.
+     */
+    unparseableSkewP: number;
     /** 95% interval on the delta, in percentage points (Newcombe). */
     ci: {
         lo: number;
@@ -64,4 +93,6 @@ export declare function armSystems(scenario: Scenario): {
     withSkill: string;
 };
 export declare function withRetry(runner: Runner, tries?: number, baseDelayMs?: number): Runner;
-export declare function runScenario(scenario: Scenario, runner: Runner): Promise<TestReport>;
+export declare function runScenario(scenario: Scenario, runner: Runner, opts?: {
+    extraNotes?: string[];
+}): Promise<TestReport>;

package/dist/testing/harness.js

@@ -29,12 +29,16 @@ export function parseScenario(file) {
     // outcome that reaches p < 0.05, so every partial result is uninterpretable
     // and the old default guaranteed a verdict nobody could stand behind.
     const trials = Math.min(50, Math.max(1, Math.round(num(doc.trials) ?? 20)));
+    const model = str(doc.model) ?? "claude-sonnet-5";
+    const judgeModel = str(doc.judge_model);
     return {
         name,
         skillPath,
         skillName: skill.name ?? path.basename(skill.dir),
         skillBody: skill.body.trim(),
-        model: str(doc.model) ?? "claude-sonnet-5",
+        model,
+        judgeModel: judgeModel ?? model,
+        judgeModelExplicit: judgeModel !== undefined,
         trials,
         task,
         judge,
@@ -60,7 +64,7 @@ async function judgeOne(runner, scenario, answer) {
     const out = await runner({
         system: JUDGE_SYSTEM,
         user: `TASK:\n${scenario.task}\n\nRUBRIC:\n${scenario.judge}\n\nASSISTANT ANSWER:\n${answer}\n\nVerdict (PASS or FAIL):`,
-        model: scenario.model,
+        model: scenario.judgeModel,
         deterministic: true,
     });
     const saysPass = /\bpass(ed|es)?\b/i.test(out);
@@ -119,7 +123,7 @@ async function runArm(runner, scenario, system) {
         passRate: scored > 0 ? (passes / scored) * 100 : 0,
     };
 }
-export async function runScenario(scenario, runner) {
+export async function runScenario(scenario, runner, opts = {}) {
     const systems = armSystems(scenario);
     // Wrap once so both the subject answers and the judge calls survive a
     // transient blip instead of throwing away the whole (paid-for) scenario.
@@ -150,11 +154,28 @@ export async function runScenario(scenario, runner) {
     if (unscored) {
         notes.push(`${unscored} trial(s) produced a judge verdict that was neither PASS nor FAIL and are excluded from the rates, not counted as failures.`);
     }
+    // Excluding a trial the judge did not answer is the right call, and it is
+    // unbiased only while the exclusions fall on both arms alike. They need not:
+    // a skill that makes answers longer, or hedged, or formatted differently can
+    // make the judge hedge too, and then one arm quietly loses more trials than
+    // the other and the two surviving pass rates are rates over different things.
+    // Tested with the same statistic and the same threshold used for the effect
+    // itself, so there is one standard of evidence in this report, not two.
+    const unparseableSkewP = fisherExactTwoSided(withSkill.unparseable, withSkill.trials, withoutSkill.unparseable, withoutSkill.trials);
+    const exclusionsAreSkewed = unscored > 0 && unparseableSkewP < 0.05;
     let verdict;
     if (withSkill.scored === 0 || withoutSkill.scored === 0) {
         verdict = "inconclusive";
         notes.push("an arm produced no scoreable trial; there is nothing to compare.");
     }
+    else if (exclusionsAreSkewed) {
+        verdict = "inconclusive";
+        notes.push(`the judge failed to answer on ${withSkill.unparseable} of ${withSkill.trials} with-skill trials and ` +
+            `${withoutSkill.unparseable} of ${withoutSkill.trials} without-skill trials, a difference this size at ` +
+            `p = ${unparseableSkewP < 0.0001 ? "<0.0001" : unparseableSkewP.toFixed(4)}. The excluded trials are not ` +
+            `spread evenly across the arms, so the two pass rates are computed over different populations and the ` +
+            `delta cannot be attributed to the skill. Tighten the rubric so the judge always answers, then re-run.`);
+    }
     else if (p >= 0.05) {
         verdict = "no measurable effect";
         if (Math.abs(deltaPoints) >= 15) {
@@ -166,14 +187,18 @@ export async function runScenario(scenario, runner) {
         verdict = "helps";
     else
         verdict = "hurts";
+    if (opts.extraNotes?.length)
+        notes.push(...opts.extraNotes);
     return {
         scenario: scenario.name,
         skill: scenario.skillName,
         model: scenario.model,
+        judgeModel: scenario.judgeModel,
         withSkill,
         withoutSkill,
         deltaPoints,
         p,
+        unparseableSkewP,
         ci,
         verdict,
         notes,

package/dist/testing/stats.d.ts

@@ -28,3 +28,19 @@ export declare function deltaInterval(withPass: number, withTrials: number, with
     lo: number;
     hi: number;
 };
+/**
+ * The smallest difference in pass rate this many trials per arm could ever
+ * call significant, in percentage points.
+ *
+ * A plan that cannot detect the effect it is looking for produces a green that
+ * means nothing, and the only place to notice that is before spending the
+ * tokens. So the dry run prints this: at 8 trials per arm nothing under about
+ * 50 points is reachable, which is worth knowing before paying for 32 API
+ * calls to find out.
+ *
+ * Computed by exhaustive search over every 2x2 the plan can produce, because
+ * the number of tables is small (trials is capped at 50, so at most 2,601
+ * Fisher evaluations) and a closed form for the exact test is not worth
+ * deriving. Returns Infinity when no outcome at this size reaches alpha.
+ */
+export declare function minimumDetectableDelta(trials: number, alpha?: number): number;

package/dist/testing/stats.js

@@ -87,3 +87,29 @@ export function deltaInterval(withPass, withTrials, withoutPass, withoutTrials)
     const hi = d + Math.sqrt((w.hi - p1) ** 2 + (p2 - o.lo) ** 2);
     return { lo: Math.round(Math.max(-1, lo) * 1000) / 10, hi: Math.round(Math.min(1, hi) * 1000) / 10 };
 }
+/**
+ * The smallest difference in pass rate this many trials per arm could ever
+ * call significant, in percentage points.
+ *
+ * A plan that cannot detect the effect it is looking for produces a green that
+ * means nothing, and the only place to notice that is before spending the
+ * tokens. So the dry run prints this: at 8 trials per arm nothing under about
+ * 50 points is reachable, which is worth knowing before paying for 32 API
+ * calls to find out.
+ *
+ * Computed by exhaustive search over every 2x2 the plan can produce, because
+ * the number of tables is small (trials is capped at 50, so at most 2,601
+ * Fisher evaluations) and a closed form for the exact test is not worth
+ * deriving. Returns Infinity when no outcome at this size reaches alpha.
+ */
+export function minimumDetectableDelta(trials, alpha = 0.05) {
+    let best = Infinity;
+    for (let a = 0; a <= trials; a++) {
+        for (let b = 0; b < a; b++) {
+            if (fisherExactTwoSided(a, trials, b, trials) < alpha) {
+                best = Math.min(best, ((a - b) / trials) * 100);
+            }
+        }
+    }
+    return best;
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export const VERSION = "0.1.2";
+export const VERSION = "0.3.0";

package/dist/weigh/anthropicExact.d.ts

@@ -4,8 +4,19 @@ import type { ToolDef } from "../core/types.js";
  * /v1/messages/count_tokens with and without the tools array (the endpoint
  * accepts `tools`; verified against the official API reference 2026-07-16).
  * Returns undefined on any failure; callers treat this as optional precision.
+ *
+ * Returns the model alongside the count, and the model is not optional in the
+ * result. Claude model lines do not share a tokenizer, so "the exact count" is
+ * exact for one model and an approximation for the next, and a number printed
+ * without the model it was measured on cannot be reproduced or compared. This
+ * is the same rule `src/weigh/window.ts` already applies to the context-window
+ * denominator: never print a figure whose basis is an assumption without
+ * naming the assumption.
  */
 export declare function countClaudeToolTokens(tools: ToolDef[], opts: {
     apiKey: string;
     model?: string;
-}): Promise<number | undefined>;
+}): Promise<{
+    tokens: number;
+    model: string;
+} | undefined>;

package/dist/weigh/anthropicExact.js

@@ -5,6 +5,14 @@ const DEFAULT_MODEL = "claude-sonnet-5";
  * /v1/messages/count_tokens with and without the tools array (the endpoint
  * accepts `tools`; verified against the official API reference 2026-07-16).
  * Returns undefined on any failure; callers treat this as optional precision.
+ *
+ * Returns the model alongside the count, and the model is not optional in the
+ * result. Claude model lines do not share a tokenizer, so "the exact count" is
+ * exact for one model and an approximation for the next, and a number printed
+ * without the model it was measured on cannot be reproduced or compared. This
+ * is the same rule `src/weigh/window.ts` already applies to the context-window
+ * denominator: never print a figure whose basis is an assumption without
+ * naming the assumption.
  */
 export async function countClaudeToolTokens(tools, opts) {
     const model = opts.model ?? DEFAULT_MODEL;
@@ -22,7 +30,7 @@ export async function countClaudeToolTokens(tools, opts) {
         if (withTools === undefined || withoutTools === undefined)
             return undefined;
         const delta = withTools - withoutTools;
-        return delta >= 0 ? delta : undefined;
+        return delta >= 0 ? { tokens: delta, model } : undefined;
     }
     catch {
         return undefined;

package/dist/weigh/weigh.js

@@ -33,13 +33,19 @@ export async function weighServer(intro, opts = {}) {
         "token counts are estimates using the o200k_base tokenizer; hosts add fixed framing text on top (see docs/METHODOLOGY.md)",
     ];
     let anthropicExactTotal;
+    let anthropicExactModel;
     if (opts.anthropicApiKey && intro.tools.length > 0) {
-        anthropicExactTotal = await countClaudeToolTokens(intro.tools, {
+        const exact = await countClaudeToolTokens(intro.tools, {
             apiKey: opts.anthropicApiKey,
             model: opts.anthropicModel,
         });
-        if (anthropicExactTotal !== undefined) {
-            notes.push("anthropic-exact measured via /v1/messages/count_tokens (tools delta)");
+        if (exact !== undefined) {
+            anthropicExactTotal = exact.tokens;
+            anthropicExactModel = exact.model;
+            // Name the model. Claude model lines do not share a tokenizer, so this
+            // figure is exact for `exact.model` and an estimate for anything else,
+            // and a reader comparing two runs has to be able to see which is which.
+            notes.push(`anthropic-exact measured via /v1/messages/count_tokens (tools delta) against ${exact.model}`);
         }
         else {
             notes.push("anthropic-exact measurement failed; showing o200k estimates only");
@@ -56,6 +62,7 @@ export async function weighServer(intro, opts = {}) {
         framingTokens,
         instructionsTokens: count(intro.instructions ?? ""),
         anthropicExactTotal,
+        anthropicExactModel,
         notes,
     };
 }

package/docs/INTEGRATIONS.md

@@ -36,6 +36,18 @@ Ratchet MCP tool-definition cost with the budget gate (commit `base.json` once w
 - run: npx efaimo weigh "npx -y your-server" --diff base.json --allow-increase 10
 ```
 
+Keep every tool findable once a host defers your catalog. `--min-distinct` fails the run
+when a tool owns no word the other tools lack, which means no search can return
+it without also returning a competitor:
+
+```yaml
+- run: npx efaimo find "npx -y your-server" --min-distinct 100
+```
+
+Start it at the number you have today rather than at 100 and raise it as you
+fix tools; the command prints the line to copy. It refuses to run on a one-tool
+catalog, where the figure is 100% by construction, rather than passing.
+
 Post the grade on the PR with `--md` (pipe into any comment action):
 
 ```yaml
@@ -108,7 +120,9 @@ the current SDK.
 
 ## Programmatic use
 
-Every capability is also a typed function:
+Every capability is also a typed function. `analyzeFind`, `runFindRules` and the
+two `find` renderers are exported alongside the rest; the rule
+tables themselves stay private, like the other two families.
 
 ```ts
 import { weighServer, introspectServer, checkSkillSet } from "efaimo";

package/docs/METHODOLOGY.md

@@ -131,19 +131,28 @@ trials. At that size 5/5 against 4/5 is +20 points and p = 1.0000.
 
 Two things the judge does, which matter for reading a result:
 
-- it runs at **temperature 0**, so the same answer grades the same way twice.
-  The subject arm stays at temperature 1, because normal behaviour is the thing
-  being measured;
+- it is asked to sample deterministically **where the model still accepts a
+  sampling parameter**. Claude removed `temperature` from the 4.7 line onward,
+  so on Sonnet 5, Opus 5 and their siblings the judge runs at the model's own
+  default and its variance is part of the measurement. The report says so on
+  every run that this applies to, rather than claiming a determinism it does
+  not have. The subject arm is unaffected: it
+  wanted temperature 1, which is the default anyway;
 - a reply that is neither PASS nor FAIL is **excluded and counted separately**,
   not scored as a failure. A refusal or an API error is not evidence about the
-  skill.
+  skill. Exclusion is only unbiased while it falls on both arms alike, so the
+  report also carries a **two-sided Fisher exact p on the unparseable counts**,
+  and a skew significant at the same 0.05 makes the verdict `inconclusive`:
+  two pass rates computed over different populations cannot be subtracted.
 
 ### What this design still cannot tell you
 
 Named here rather than left for a reader to discover:
 
-- **The judge is the same model as the subject.** A separate judge model would
-  be stronger.
+- **The judge defaults to the same model as the subject**, so part of any
+  measured effect is a model preferring its own output. `judge_model:` in the
+  scenario, or `--judge-model`, points it at another model, and the report
+  prints both. Subject and judge may be different providers.
 - **The control arm receives no system prompt at all**, so "the skill's
   content" is confounded with "having any system prompt". A length-matched
   placebo is the fix and is not implemented.
@@ -151,3 +160,98 @@ Named here rather than left for a reader to discover:
   show the method works, not that skills in general do or do not help.
 
 Treat a single scenario as evidence about that scenario.
+
+## `efaimo find`: findability
+
+A host may mark tools `defer_loading: true`, which keeps their definitions out
+of the system-prompt prefix until a search returns them. Anthropic lists five
+conditions for turning that on, joined by "any of the following apply", and two
+of them can be checked from a tool list: **ten or more tools**, or **more than
+10k tokens of definitions**. `find` checks both and names the one that fired.
+An earlier version implemented only the token clause, which told a reader that
+a 24-tool, 3.5k-token catalog was probably loaded up front when Anthropic's
+first condition already applied to it.
+
+Under deferral, a tool nothing surfaces costs no context and provides no
+capability, so "can this be found" becomes a separate question from "what does
+this cost" and "how good is this tool".
+
+`find` answers it with two numbers that are **not the same kind of claim**, and
+prints both with their denominators. In JSON they are `data.distinct` and
+`data.probe`; the terminal uses the same two words.
+
+### `distinct`: a property of the catalog
+
+For every tool, which of its terms does no other tool in the catalog have?
+
+If the answer is none, then every word that tool contains appears somewhere
+else, so **no query exists that matches it without also matching a
+competitor**. That is not a prediction about a particular search. It follows
+from the index, and the only assumption in it is the tokenizer.
+
+The precise limit of the claim, stated because it is easy to overstate: a tool
+with no exclusive vocabulary can still be ranked *first* for a shared query,
+because BM25 also weighs term frequency and document length. What it can never
+do is come back alone. Owning a word is a much stronger position than winning a
+tie-break.
+
+Terms come from the four fields the tool search documentation names as
+searchable: **tool name, description, argument names, argument descriptions**.
+Tokenization splits camelCase, `snake_case` and `kebab-case` onto the same
+terms, lowercases, drops single characters, and does no stemming, so `page` and
+`pages` are different terms (`src/find/tokenize.ts`, identified in JSON as
+`data.method.tokenizer`, a string that changes when the splitting rules do).
+English function words are excluded from ownership as well as from queries: a
+tool can be the only one in a catalog that says "the", and counting that as
+vocabulary it owns would be true and useless.
+
+**`title` is deliberately not indexed**, though MCP tools may carry one.
+Anthropic's list of searchable fields does not include it, and a `title` is
+usually the name restated for humans, so reading it would put the tool's own
+name back into its own probe. Indexing a field the real search cannot read also
+makes the number optimistic: a tool would "own" a word no query can reach.
+Measured cost of getting this wrong: Notion's server scored 17/24 with `title`
+indexed and 16/24 without, and the 16 is the honest one.
+
+**At one tool the number cannot be computed.** Every term is trivially
+exclusive, so the figure is 100% for any tool whatsoever. The report says so and
+`--min-distinct` refuses to be evaluated rather than reporting a pass.
+
+### `probe`: a simulation, and a saturated one
+
+BM25 (k1=1.2, b=0.75) over those same fields, with each tool queried using the
+highest tf-idf terms **of its own description** and a result window of 5, which
+is the documented default number of results a search returns.
+
+Two honest limits:
+
+- The real search runs server-side. Its analyzer and parameters are not
+  published, so this is a model of a documented mechanism, not a reproduction.
+- **It saturates.** Measured on four public servers: 13/13, 24/24, 26/26 and
+  24/24, and every query variant tried (tf-idf, raw tf, leading terms) gave the
+  same 100%. The query comes from the tool's own words, which is friendlier
+  than anything a user would type. Treat it as a floor test that catches an
+  empty description or a literal duplicate, not as a ranking.
+  [The findability report](../research/findability/REPORT.md) has the numbers
+  and the commands that reproduce them.
+
+The query deliberately excludes the tool's **name** and its **title**. An
+earlier version included both and the metric could barely fail: a unique name
+token has maximal idf, so it entered every query and pulled its own tool to the
+top, and two tools with identical descriptions both scored a clean first place.
+The name stays in the index, so a name whose words echo the description still
+helps it rank.
+
+### Why there is no findability grade
+
+Because the two numbers answer different questions and only one of them is a
+measurement rather than a model, and because a letter would have inherited the
+defect the quality grade already has: it cannot see size. See ADR-030. The gate
+is `--min-distinct`, which the operator sets, on the number that can actually
+fail at two tools and up.
+
+The colour the terminal puts on `distinct` is not a grade either: red means the
+E141 condition holds (some tool owns nothing), green means it does not. An
+earlier version banded it at 95 and 80 percent, two cutoffs that appeared in no
+rule and no document, inside the one command whose design note says it does not
+grade.