@browserstack/mcp-server 1.5.0-beta.15 → 1.5.0-beta.17

package/dist/tools/capability-registry/bind.js

@@ -200,6 +200,22 @@ function coerceType(value, param, label = param.name) {
             return false;
         throw new InvocationError(`'${label}' must be true or false`);
     }
+    // NO DECLARED TYPE: pass the value through as given.
+    //
+    // The fallthrough below is String(value), which is right for a declared string and
+    // silently destructive for anything the spec left untyped. create_report_v2 declares
+    // `mail_to` and `report_filters` with no type and the API wants objects for both, so a
+    // correct payload was serialised to the literal "[object Object]" and refused:
+    //
+    //   The property '#/mail_to' of type string did not match the following type: object
+    //
+    // The caller sent the right thing, this layer broke it, and the server's message blames
+    // the caller for a string it never wrote. An untyped parameter means the spec declines to
+    // say what shape it is — which is a reason to leave it alone, not to guess "string".
+    const untyped = !expected;
+    if (untyped && (typeof value === "object" || typeof value === "boolean")) {
+        return value;
+    }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));
@@ -244,8 +260,33 @@ export function bind(capability, args) {
         // misspelled filter would return a larger result set that looks like a correct answer.
         const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
         if (unknown.length > 0) {
+            // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
+            //
+            // Most of these endpoints want a nested body — Rails `params.require(:test_case)` —
+            // and the fields declare that as `json_path: /test_case/name`, so this layer
+            // assembles the wrapper itself and the caller sends the fields flat. A caller who
+            // wraps it by hand therefore sends a key that is never a declared param, and the
+            // bare message reads as "that field does not exist" when the truth is the opposite:
+            // it exists, and building it is our job.
+            //
+            // Worth special-casing because the guidance itself has been telling callers to wrap:
+            // 25 tm capabilities carried a line describing the WIRE format to a caller who never
+            // writes the wire. Those lines are being corrected, but an agent working from an
+            // older artifact, or reasoning from the Rails convention, lands here either way.
+            const wrappers = new Set(params
+                .map((param) => param.json_path)
+                .filter((path) => Boolean(path))
+                .map((path) => path.replace(/^\//, "").split("/")[0])
+                .filter((segment) => segment && !byName.has(segment)));
+            const sentAWrapper = unknown.filter((name) => wrappers.has(name));
             throw new InvocationError(`unknown ${group}: ${unknown.sort().join(", ")}. accepted: ` +
-                `${[...byName.keys()].sort().join(", ") || "none"}`);
+                `${[...byName.keys()].sort().join(", ") || "none"}` +
+                (sentAWrapper.length > 0
+                    ? `. ${sentAWrapper.sort().join(" and ")} ` +
+                        `${sentAWrapper.length > 1 ? "are wrappers" : "is a wrapper"} this ` +
+                        `surface builds for you from each field's json_path — send the fields ` +
+                        `directly instead of nesting them`
+                    : ""));
         }
         for (const [name, raw] of Object.entries(supplied)) {
             const param = byName.get(name);

package/dist/tools/capability-registry/egress.js

@@ -83,6 +83,54 @@ export function authHeaders(credentials, auth = DEFAULT_AUTH) {
     throw new InvocationError(`unsupported auth scheme for this product: ` +
         `${JSON.stringify({ type: auth.type, scheme: auth.scheme })}`);
 }
+/** Longest response text kept when it is not JSON. Enough for an error, not a whole page. */
+const TEXT_BODY_LIMIT = 2000;
+/**
+ * Read the response, and NEVER silently discard it.
+ *
+ * This used to parse the body only when the content-type said JSON and return `null`
+ * otherwise, which meant an error could arrive as `{status: 500, body: null}` — a status
+ * code and nothing else. That is worse than it sounds: an unhandled exception in a Rails
+ * app renders `text/html`, so the one case where you most need the message is exactly the
+ * case where the content-type is not JSON. It also made two very different situations
+ * indistinguishable — "the product sent no message" and "we threw the message away" — and
+ * a live probe of `test_case_results_v1` had to leave that ambiguity open in its findings
+ * because nothing downstream could tell which had happened.
+ *
+ * So: JSON is parsed as before. Anything textual is kept as a truncated string. Malformed
+ * JSON keeps its raw text rather than becoming `null`, because a body that fails to parse
+ * is itself the diagnosis. Binary is described rather than decoded — dumping PDF bytes
+ * into an agent's context helps nobody, but knowing a PDF arrived does.
+ */
+async function readBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    // Anything that is not plausibly text: report what came back without decoding it.
+    const textual = !contentType ||
+        /^text\//i.test(contentType) ||
+        /\b(json|xml|yaml|csv|javascript|x-www-form-urlencoded)\b/i.test(contentType);
+    if (!textual) {
+        const size = response.headers.get("content-length");
+        return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
+    }
+    const raw = await response.text().catch(() => "");
+    if (!raw.trim())
+        return null;
+    if (contentType.includes("json")) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Declared JSON that is not JSON. The text is the evidence; keep it.
+            return truncate(raw);
+        }
+    }
+    return truncate(raw);
+}
+function truncate(text) {
+    return text.length <= TEXT_BODY_LIMIT
+        ? text
+        : `${text.slice(0, TEXT_BODY_LIMIT)}… [truncated, ${text.length} chars total]`;
+}
 /** A fetch-based transport. Redirects are NOT followed. */
 export function fetchTransport(timeoutMs = 45_000) {
     return async (method, url, headers, query, body) => {
@@ -106,12 +154,10 @@ export function fetchTransport(timeoutMs = 45_000) {
                 redirect: "manual",
                 signal: controller.signal,
             });
-            let parsed = null;
-            const contentType = response.headers.get("content-type") || "";
-            if (contentType.includes("json")) {
-                parsed = await response.json().catch(() => null);
-            }
-            return { status: response.status, body: parsed };
+            return {
+                status: response.status,
+                body: await readBody(response),
+            };
         }
         catch {
             // Upstream detail stays out of the reply; the resolver treats status 0 as a failed call.

package/dist/tools/capability-registry/index-loader.js

@@ -337,7 +337,42 @@ function resolveNode(product, node, seen) {
         // revisit a name already on this path.
         if (!target || seen.has(key))
             return node;
-        return resolveNode(product, target, new Set([...seen, key]));
+        const resolved = resolveNode(product, target, new Set([...seen, key]));
+        // KEYS WRITTEN BESIDE THE REF SURVIVE IT, AND WIN.
+        //
+        // This used to return the target and drop every sibling, which silently ate 16 nodes
+        // in the shipped tm index: 14 authored descriptions and two `nullable: true` flags.
+        // The losses are exactly the caveats hardest to rediscover — "only when no step
+        // results were submitted", "Present only on root-folder creation", and a `nullable`
+        // marking the one field that comes back NULL when a search fails, which is the
+        // absent-versus-explicitly-null distinction a caller cannot otherwise make.
+        //
+        // It also cost real work downstream. A live probe reported one of those caveats as a
+        // missing conditional and it had been written all along — this resolver removed it
+        // between the author and the caller. Worse, the product team began splitting shared
+        // schemas so a caveat would have somewhere to live that survived, trading a lost
+        // sentence for two descriptions of one serializer that then drift apart.
+        //
+        // SIBLINGS WIN over the resolved target, not the reverse. A description written at the
+        // reference site is about THAT usage — "only when no step results were submitted" is
+        // true of one consumer of TestResult, not of TestResult everywhere — which is the
+        // whole reason it was written beside the ref instead of on the schema.
+        const siblings = {};
+        for (const [field, value] of Object.entries(node)) {
+            if (field !== "$schema" && field !== "$response")
+                siblings[field] = value;
+        }
+        if (Object.keys(siblings).length === 0)
+            return resolved;
+        if (typeof resolved !== "object" ||
+            resolved === null ||
+            Array.isArray(resolved)) {
+            return resolved;
+        }
+        return {
+            ...resolved,
+            ...resolveNode(product, siblings, seen),
+        };
     }
     const out = {};
     for (const [field, value] of Object.entries(node)) {

package/dist/tools/capability-registry/register.d.ts

@@ -18,6 +18,14 @@ import { BrowserStackConfig } from "../../lib/types.js";
 import { Credentials, Transport } from "./egress.js";
 import { CapabilityRegistry } from "./index-loader.js";
 export declare const PERMISSION_VALUES: readonly ["not_asked", "granted", "denied"];
+/**
+ * The search-side twin of `user_permission`: did a human choose the product, or did you?
+ *
+ * No `denied`. A refused write is a thing the caller must not do; a refused product choice
+ * is not a state — the user either named one, in which case you search it, or has not been
+ * asked, in which case there is nothing to search yet.
+ */
+export declare const PRODUCT_CHOICE_VALUES: readonly ["not_asked", "user_confirmed"];
 export interface RegistryDeps {
     registry: CapabilityRegistry;
     /**

package/dist/tools/capability-registry/register.js

@@ -20,8 +20,16 @@ import { indexPaths, isEnabled, resolveBaseUrl } from "./config.js";
 import { fetchTransport } from "./egress.js";
 import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
 import { invoke } from "./resolve.js";
-import { searchCapabilities, vocabularyOf } from "./search.js";
+import { ambiguousProducts, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
+/**
+ * The search-side twin of `user_permission`: did a human choose the product, or did you?
+ *
+ * No `denied`. A refused write is a thing the caller must not do; a refused product choice
+ * is not a state — the user either named one, in which case you search it, or has not been
+ * asked, in which case there is nothing to search yet.
+ */
+export const PRODUCT_CHOICE_VALUES = ["not_asked", "user_confirmed"];
 /**
  * The tool-adder the server factory calls.
  *
@@ -73,10 +81,13 @@ export function addCapabilityRegistryToolsFromConfig(server, config) {
 function ok(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
-function failed(message) {
+function failed(message, extra) {
     return {
         content: [
-            { type: "text", text: JSON.stringify({ ok: false, error: message }) },
+            {
+                type: "text",
+                text: JSON.stringify({ ok: false, error: message, ...extra }),
+            },
         ],
         isError: true,
     };
@@ -114,9 +125,10 @@ export function addCapabilityRegistryTools(server, deps, config) {
             // Telemetry must not decide whether a tool call succeeds.
         }
     };
-    tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach, with a one-line summary each " +
-        "and the entities each one models. Start here when you do not know which product a " +
-        "task belongs to.", {}, {
+    tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach: what each one does, the " +
+        "entities it models, and a line saying what each entity is. START HERE — " +
+        "searchCapability needs a product, and this is what tells you which one. If two " +
+        "products could both fit the task, ask the user rather than choosing for them.", {}, {
         title: "List Capability Products",
         readOnlyHint: true,
         destructiveHint: false,
@@ -124,28 +136,34 @@ export function addCapabilityRegistryTools(server, deps, config) {
         openWorldHint: false,
     }, async () => {
         track("listProducts");
-        const info = registry.buildInfo();
         return ok({
-            build_id: registry.buildId,
             products: registry.productNames().map((name) => ({
                 name,
                 summary: registry.index.products[name].summary,
-                // THE VOCABULARY, UP FRONT. Routing is this tool's whole job, and a summary
-                // alone does not do it: "add a tag to xyz test" reads as either product until
-                // you can see that `tag` exists in one and not the other. Measured across both
-                // products, 139 of 147 terms resolve to exactly one — so this settles 95% of
-                // the question before a single search, and makes the remaining 8 (run, project,
-                // report, result, folder, workspace, execution, history) visibly ambiguous
-                // instead of silently so.
+                // THE ENTITIES AND WHAT EACH ONE IS. Routing is this tool's whole job, and a
+                // product summary alone does not do it: "add a tag to xyz test" reads as
+                // either product until you can see that `tag` exists in one and not the other.
+                // The one-line description is what makes each name mean something — `version`
+                // alone does not say whether it versions a test case or a project — so an
+                // agent can choose here instead of calling describeEntity once per entity to
+                // find out, which for tm is 19 calls at ~1.4KB apiece.
                 //
-                // ~1.9KB for both products, on a tool called once for routing. The same content
-                // reaches a caller reactively via searchCapability's weak-match block; this is
-                // the proactive half, for the agent that looks before it leaps.
-                entities: vocabularyOf(registry.index.products, name)[name] ?? [],
-                // Provenance for logging and cache-busting only — capability resolution must
-                // never depend on it.
-                build_id: info[name]?.build_id,
-                ...(info[name]?.version ? { version: info[name].version } : {}),
+                // NAME AND DESCRIPTION ONLY. The aliases used to travel here too, and they are
+                // the wrong half for this job: they answer "what else is this called", which
+                // matters when a search has already failed on vocabulary, not when choosing a
+                // product. They still reach the caller at exactly that moment, in
+                // searchCapability's weak-match block, where the full vocabulary is the answer
+                // rather than 2.5KB of speculative context on every routing call.
+                entities: (vocabularyOf(registry.index.products, name)[name] ?? []).map(({ entity, description }) => ({
+                    entity,
+                    ...(description ? { description } : {}),
+                })),
+                // NO build_id OR version. They are provenance — for our logs and for cache
+                // busting — and capability resolution must never depend on them, which means
+                // no caller has anything to do with them. They rode on the one call an agent
+                // makes before it knows anything, costing context to say nothing actionable.
+                // Still on searchCapability's response, where a support question about which
+                // index answered can actually be traced to a result.
             })),
         });
     });
@@ -182,20 +200,22 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return ok({ product, entity, ...doc });
     });
-    tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, optionally narrowed to one " +
-        "entity, product or mode. " +
-        `Currently loaded products: ${productList} — call listProducts for what each does. ` +
+    tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, within ONE product. " +
+        `You must say which: ${productList}. If the task does not name it unambiguously, ` +
+        "call listProducts first — it returns what each product does, the entities each " +
+        "models, and what every entity means, which is what settles the choice. Where two " +
+        "products use the same word for different things, ask the user rather than picking. " +
         "Search matches the product's OWN words, not synonyms. When your words are not the " +
         "product's, the response says so: `weak_match: true` with a `suggested_vocabulary` " +
         "map of the product's entities and their aliases. Results are still returned, but " +
         "treat them as unconfirmed — pick the closest entity from that map and search again " +
         "using its vocabulary, or call describeEntity on it for the fuller picture. That one " +
         "extra round trip is far cheaper than invoking the wrong capability. " +
-        "Narrowing with `product` or `entity` sharpens results further. " +
+        "Narrowing further with `entity` sharpens results. " +
         "THIS IS A SHORTLIST, NOT A CONTRACT. Each result carries only what you need to " +
-        "CHOOSE: `name` (the handle), `product` (which product owns it — results can span " +
-        "products), `mode` (whether it writes), `intent` and `guidance` (what it does and " +
-        "what goes wrong), and `method`/`path` for products that publish no name yet. " +
+        "CHOOSE: `name` (the handle), `product`, `mode` (whether it writes), `intent` and " +
+        "`guidance` (what it does and what goes wrong), and `method`/`path` for products " +
+        "that publish no name yet. " +
         "It does NOT carry parameters or response shapes. Once you have picked one, call " +
         "describeCapability for its full contract, then invokeCapability. Fetching the " +
         "contract only for the one you chose is the difference between ~1k and ~8.6k tokens " +
@@ -207,9 +227,31 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .string()
             .optional()
             .describe("Restrict to one entity (listProducts names them)."),
-        product: productArg()
-            .optional()
-            .describe(`Restrict to one product: ${productList}. Omit to search all of them.`),
+        // REQUIRED, and the reason is the tool that is NOT being called. listProducts
+        // carries the routing data — each product's purpose, its entities, and what every
+        // entity means — but nothing obliged an agent to read it: a search that worked
+        // without naming a product meant the routing step could always be skipped, and an
+        // optional step in front of a working one is a step that does not happen. Requiring
+        // the argument makes the ordering structural instead of advisory.
+        //
+        // It costs one listProducts call on queries that were already unambiguous — 139 of
+        // 147 vocabulary terms resolve to a single product — and buys the eight that are
+        // not (run, project, report, result, folder, workspace, execution, history), where
+        // the old behaviour was to silently pick whichever product ranked higher. A wasted
+        // round trip against a silent wrong-product answer is not a close trade.
+        product: productArg().describe(`Which product to search: ${productList}. Call listProducts if the task does ` +
+            `not make it obvious, and ask the user when two products could both fit.`),
+        // REQUIRED, and self-reported, exactly like `user_permission` on a write. The
+        // server cannot see whether you asked anyone; what it can do is refuse to answer a
+        // question only the user can settle, and make claiming otherwise an explicit act
+        // rather than an omission.
+        product_choice: z
+            .enum(PRODUCT_CHOICE_VALUES)
+            .describe("'user_confirmed' only when the user named the product, or the task names it " +
+            "unmistakably. 'not_asked' otherwise — then a query that could mean either " +
+            "product is refused and told what to ask, instead of being answered for the " +
+            "wrong one. Never search each product in turn and merge the results: that is " +
+            "the guess this argument exists to prevent."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -221,8 +263,61 @@ export function addCapabilityRegistryTools(server, deps, config) {
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async ({ query, entity, product, mode, limit }) => {
+    }, async ({ query, entity, product, product_choice, mode, limit }) => {
         track("searchCapability");
+        // THE GATE. Nothing here can tell whether a human was asked — same as the write
+        // gate, which also takes the caller's word. What it can do is refuse to answer a
+        // question that is genuinely the user's, so that answering it anyway takes a
+        // deliberate claim instead of silence.
+        //
+        // Only when the query itself cannot settle the choice: every recognised word is one
+        // both products claim. 27 of the 198 eval queries, against 135 if constituent words
+        // counted. `entity` is an explicit narrowing, so a caller that named one has already
+        // been specific enough and is not asked again.
+        if (product_choice !== "user_confirmed" && !entity) {
+            const ambiguity = ambiguousProducts(registry.index.products, query);
+            if (ambiguity.products.length > 1) {
+                // EVERYTHING NEEDED TO ASK, IN THE REFUSAL. Telling the agent to go and call
+                // listProducts costs a round trip and still leaves it composing a question out
+                // of nothing — so it tends to guess instead, which is the behaviour being
+                // stopped. What makes the choice answerable is what each product calls the
+                // shared word and what it means THERE: tm's project owns folders and test
+                // cases, Load Testing's does not.
+                const options = ambiguity.products.map((name) => {
+                    const entities = registry.index.products[name]?.entities ?? {};
+                    const senses = ambiguity.terms
+                        .map((term) => {
+                        const key = Object.keys(entities).find((candidate) => [
+                            candidate,
+                            ...(entities[candidate].aliases ?? []),
+                        ].some((word) => terms(word).map(singular).join(" ") === term));
+                        const doc = key ? entities[key] : undefined;
+                        return doc
+                            ? { term, entity: key, means: doc.description }
+                            : undefined;
+                    })
+                        .filter(Boolean);
+                    return {
+                        product: name,
+                        summary: registry.index.products[name]?.summary,
+                        ...(senses.length ? { shared_terms: senses } : {}),
+                    };
+                });
+                return failed(`'${query}' could mean ${ambiguity.products.join(" or ")} — ` +
+                    `${ambiguity.terms.map((t) => `'${t}'`).join(", ")} ` +
+                    `${ambiguity.terms.length === 1 ? "belongs" : "belong"} to both. ` +
+                    "Put the choice in `clarify` to the USER in their own terms, wait for an " +
+                    "answer, then resend with product_choice='user_confirmed'. Do NOT search " +
+                    "each product in turn and merge the results — that answers the question " +
+                    "instead of asking it.", {
+                    clarify: {
+                        question: `Which product do you mean — ${ambiguity.products.join(" or ")}?`,
+                        shared: ambiguity.terms,
+                        options,
+                    },
+                });
+            }
+        }
         const { hits, weak, top_matched, ...rest } = searchCapabilities(registry.index.products, query, {
             entity,
             product,
@@ -230,22 +325,35 @@ export function addCapabilityRegistryTools(server, deps, config) {
             limit,
         });
         return ok({
-            build_id: registry.buildId,
+            // NO build_id. It is provenance — for our logs and for cache busting — and
+            // resolution must never depend on it, which is exactly why no caller has anything
+            // to do with it. It was also the WHOLE registry's id, so a search scoped to one
+            // product still announced every other product's build: metadata about builds the
+            // caller did not ask about and cannot act on. The startup log already records
+            // what loaded, which is where a question about a stale index gets answered.
+            //
             // A SHORTLIST: only what choosing requires. Parameters and response shapes are 86%
             // of a full record and are needed for exactly ONE of the eight — the one the caller
             // picks — so they move to describeCapability. Measured over eight queries: 8.6k
             // tokens a search becomes ~1k, and even describing all eight results still costs
             // slightly less than today.
             //
-            // `product` is here because results span products and the caller cannot otherwise
-            // tell a Load Testing row from a Test Management one. `method`/`path` are here
-            // because Load Testing publishes no names at all — without them its rows would be
-            // unaddressable, which is worse than verbose.
-            capabilities: hits.map(({ product: owner, capability }) => ({
-                ...(capability.name ? { name: capability.name } : {}),
-                product: owner,
-                method: capability.method,
-                path: capability.path,
+            // NO ROUTE, AND NO PRODUCT. Both were justified and both justifications expired.
+            //
+            // `method`/`path` were unconditional because Load Testing published no names, so
+            // its rows would otherwise have been unaddressable. It now names all 20, as tm
+            // names all 173 — every row on this surface is reachable by name. Publishing the
+            // route anyway contradicts the premise the whole registry rests on: an agent
+            // addresses a capability by a handle that outlives the route. They remain as a
+            // fallback for a product that ships unnamed capabilities, emitted only for the
+            // rows that actually need them, which today is none.
+            //
+            // `product` was here because results could span products. They cannot: `product`
+            // is a required argument, so every row is the product the caller named.
+            capabilities: hits.map(({ capability }) => ({
+                ...(capability.name
+                    ? { name: capability.name }
+                    : { method: capability.method, path: capability.path }),
                 mode: capability.mode,
                 entity: capability.entity,
                 ...(capability.intent ? { intent: capability.intent } : {}),
@@ -332,11 +440,24 @@ export function addCapabilityRegistryTools(server, deps, config) {
             // Dropped rather than overwritten: the raw field holds `{"$response": …}` pointers,
             // and spreading the capability would leak them through whenever the resolved value
             // is absent.
-            const { responses: unresolved, ...contract } = capability;
+            const { responses: unresolved, method, path, ...contract } = capability;
             void unresolved;
             return ok({
-                build_id: registry.buildId,
+                // No build_id here either, same reason. `product` stays: describeCapability
+                // resolves by NAME and its product argument is optional, so the answer has to
+                // say whose contract came back.
                 product: owner,
+                // NO ROUTE, for the same reason the shortlist has none. A named capability is
+                // invoked by its name; the route is how WE reach the product, not something
+                // the caller acts on, and a contract that shows both invites the caller to
+                // hold the half that breaks when `/edit` becomes `/edit-v2`. The parameters
+                // below still carry `path_params`, so the caller knows what to supply — it
+                // just never sees the template they are substituted into.
+                //
+                // Emitted only when there is no name to use instead, which is what
+                // invokeCapability falls back to for a product that publishes none. No shipped
+                // product is in that state today.
+                ...(capability.name ? {} : { method, path }),
                 ...contract,
                 ...(responses ? { responses } : {}),
             });

package/dist/tools/capability-registry/search.d.ts

@@ -29,6 +29,21 @@ export declare function terms(text: string | undefined): string[];
  * for no additional match.
  */
 export declare function termForms(term: string): string[];
+/**
+ * ONE canonical spelling of a word, so two spellings of a noun cannot look like two terms.
+ *
+ * `termForms` is deliberately generous — it offers every candidate and lets substring
+ * containment sort them out. Canonicalising needs the opposite: exactly one answer, and
+ * the right one. Taking the SHORTEST candidate is what a first cut did, and it folded
+ * `cases` to `cas`, so the vocabulary entry `test case` matched no query containing "test
+ * cases" — the phrase it exists for. The ambiguity check then fell through to `test`
+ * alone, reaching the right verdict by the wrong route.
+ *
+ * Strip `es` only after a sibilant, where English actually inserts it (`boxes`,
+ * `batches`, `statuses`). Otherwise strip the single `s`, which is right for the `-e`
+ * plurals this vocabulary is full of: case, suite, phase, template.
+ */
+export declare function singular(word: string): string;
 export declare function modeHint(query: string | undefined): "" | Mode;
 export declare function wantsCollection(query: string | undefined): boolean;
 /**
@@ -70,9 +85,36 @@ export interface SearchResult {
     coverage: number;
     weak: boolean;
 }
+/** Which products a query could plausibly be about, when more than one could. */
+export interface ProductAmbiguity {
+    /** The products that claim the query's words. Empty when the query settles itself. */
+    products: string[];
+    /** The shared vocabulary that caused it — what to put in front of the user. */
+    terms: string[];
+}
+/**
+ * Products whose OWN vocabulary the query hits, when no word in the query settles it.
+ *
+ * Requiring `product` made every CALL unambiguous and did nothing about the agent making
+ * two of them: "list all projects" was answered by searching tm, then Load Testing, then
+ * merging — a question about which product the user meant, answered by guessing both.
+ * Tool-description prose asking the agent to check with the user is a suggestion it is
+ * free to decline, and declining is cheaper than interrupting someone.
+ *
+ * WHOLE VOCABULARY ENTRIES, never their constituent words. Splitting them makes almost
+ * everything look shared: Load Testing's "load test" and tm's "test case" both yield
+ * `test`, which flagged 135 of the 198 eval queries. Matching entries whole flags 27.
+ *
+ * A UNIQUE TERM SETTLES IT. "create a test case in a folder" contains `folder`, which
+ * both products claim, and `test case`, which only tm does — so the query has already
+ * answered the question and there is nothing to ask. Only queries whose every recognised
+ * word is shared are genuinely undecided.
+ */
+export declare function ambiguousProducts(products: Record<string, ProductIndex>, query: string | undefined): ProductAmbiguity;
 /** One entity's caller-facing vocabulary: what it is called, and what else it is called. */
 export interface VocabularyEntry {
     entity: string;
+    description?: string;
     aliases?: string[];
 }
 /**
@@ -84,10 +126,14 @@ export interface VocabularyEntry {
  * language model, and given tm's entity list it maps bucket -> folder without effort. It
  * just cannot guess the list unprompted.
  *
- * Aliases only, and `title` dropped as a near-duplicate of `entity` ("Test run" next to
- * `test_run` buys nothing). The entity `key_facts` are richer prose but ten times the size,
- * and a caller who needs them can ask describeEntity once it knows which entity to ask
- * about — which is exactly what this hands over.
+ * Aliases and a one-line `description`; `title` stays dropped as a near-duplicate of
+ * `entity` ("Test run" next to `test_run` buys nothing). Aliases alone route but do not
+ * DEFINE — `result -> outcome, execution-result, test-result` never says whether that is
+ * the per-case verdict inside a run or a run-level rollup — so an agent holding names and
+ * aliases has exactly one way to find out, which is describeEntity once per entity. For
+ * tm that is 19 calls at ~1.4KB each, ~27KB, to answer what ~1.6KB of description answers
+ * here for every entity at once. The `key_facts` remain out: ten times the size, and the
+ * caller can ask describeEntity for the one entity it settles on.
  *
  * Its share of the response grew when search became a shortlist: 3.2KB against a 38KB full
  * search was 8%, against a 6.8KB shortlist it is nearly half. The absolute cost did not