@browserstack/mcp-server 1.5.0-beta.11 → 1.5.0-beta.12

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

@@ -8,6 +8,154 @@
  * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
  */
 import { InvocationError } from "./index-loader.js";
+/**
+ * String formats worth ENFORCING, as opposed to merely publishing.
+ *
+ * A validator that rejects a correct value is worse than no validator: the caller cannot
+ * route around it, and the request that would have worked never leaves. So this covers only
+ * the formats where "wrong" is unambiguous and a legitimate value cannot trip it.
+ *
+ * tm declares eight formats. `date`, `date-time` and `uuid` are here. `email` and `uri` are
+ * deliberately NOT — every compact regex for either rejects addresses and URLs that servers
+ * accept, and being wrong in that direction blocks real work. `int64`, `float` and `binary`
+ * say what a number or blob is, which `type` already covers.
+ */
+const FORMATS = {
+    date: {
+        // A real calendar date, so 2026-02-31 fails rather than being reformatted.
+        test: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v) &&
+            !Number.isNaN(Date.parse(`${v}T00:00:00Z`)) &&
+            new Date(`${v}T00:00:00Z`).toISOString().startsWith(v),
+        want: "a date (YYYY-MM-DD)",
+    },
+    "date-time": {
+        // Permissive on purpose: offset or Z, optional fractional seconds. Tightening this
+        // buys nothing and starts rejecting timestamps the product would have taken.
+        test: (v) => /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$/.test(v) && !Number.isNaN(Date.parse(v)),
+        want: "a date-time (e.g. 2026-01-31T09:30:00Z)",
+    },
+    uuid: {
+        test: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v),
+        want: "a UUID",
+    },
+};
+/**
+ * A declared `pattern`, compiled once, or undefined if it will not compile here.
+ *
+ * `u` because tm's patterns use `\p{L}`/`\p{N}`, which are a syntax error without it. A
+ * pattern this engine cannot compile is SKIPPED rather than thrown: the index is generated
+ * from someone else's spec, and refusing to invoke a working endpoint because its regex
+ * dialect differs would be our bug landing on the caller.
+ */
+const patternCache = new Map();
+function compiled(pattern) {
+    if (!patternCache.has(pattern)) {
+        let regex;
+        try {
+            regex = new RegExp(pattern, "u");
+        }
+        catch {
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch {
+                regex = undefined;
+            }
+        }
+        patternCache.set(pattern, regex);
+    }
+    return patternCache.get(pattern);
+}
+/**
+ * Every constraint the parameter declares, checked against the COERCED value.
+ *
+ * Runs inside `bind`, which register.ts calls dry before the write-consent gate — so a
+ * value that breaks a constraint is refused before the user is asked to approve anything,
+ * and nothing reaches egress.
+ *
+ * `label` carries the parent name for a nested field, so the message names `test_case.name`
+ * rather than a bare `name` the caller would have to go looking for.
+ */
+function checkConstraints(value, param, label = param.name) {
+    const fail = (what) => {
+        throw new InvocationError(`'${label}' ${what}`);
+    };
+    if (typeof value === "number") {
+        if (param.minimum !== undefined && value < param.minimum)
+            fail(`must be at least ${param.minimum}`);
+        if (param.maximum !== undefined && value > param.maximum)
+            fail(`must be at most ${param.maximum}`);
+        if (param.multipleOf !== undefined && param.multipleOf > 0) {
+            // Scale BOTH to integers before the modulo: 0.3 % 0.1 is 0.09999… in binary floating
+            // point and would reject a value the product accepts. The scale has to cover the
+            // value's decimals as well as the step's — scaling by the step alone rounds 0.25 to
+            // 3 against a step of 1, which then divides evenly and lets a bad value through.
+            const scale = 10 ** Math.max(decimals(param.multipleOf), decimals(value));
+            if (Math.round(value * scale) % Math.round(param.multipleOf * scale) !==
+                0)
+                fail(`must be a multiple of ${param.multipleOf}`);
+        }
+    }
+    if (typeof value === "string") {
+        if (param.minLength !== undefined && value.length < param.minLength)
+            fail(`must be at least ${param.minLength} character(s)`);
+        if (param.maxLength !== undefined && value.length > param.maxLength)
+            fail(`must be at most ${param.maxLength} character(s)`);
+        if (param.pattern) {
+            const regex = compiled(param.pattern);
+            if (regex && !regex.test(value))
+                fail(`must match ${param.pattern}`);
+        }
+        const format = param.format ? FORMATS[param.format] : undefined;
+        if (format && !format.test(value))
+            fail(`must be ${format.want}`);
+    }
+    if (Array.isArray(value)) {
+        if (param.minItems !== undefined && value.length < param.minItems)
+            fail(`must have at least ${param.minItems} item(s)`);
+        if (param.maxItems !== undefined && value.length > param.maxItems)
+            fail(`must have at most ${param.maxItems} item(s)`);
+        if (param.uniqueItems) {
+            const seen = new Set(value.map((item) => JSON.stringify(item)));
+            if (seen.size !== value.length)
+                fail("must not contain duplicate items");
+        }
+    }
+}
+/** Decimal places, for scaling `multipleOf` out of floating point. */
+function decimals(n) {
+    const text = String(n);
+    const dot = text.indexOf(".");
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+/**
+ * The declared fields one level inside an object, or inside each item of an array.
+ *
+ * Only what `fields` names is checked, and an undeclared key is left alone — `fields` is a
+ * projection of the shape, not a closed contract, so rejecting the rest would refuse valid
+ * bodies. That is the opposite of the top level, where the full parameter list IS known and
+ * an unknown name is an error.
+ */
+function checkFields(value, param) {
+    if (!param.fields?.length)
+        return;
+    const items = Array.isArray(value) ? value : [value];
+    for (const item of items) {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const field of param.fields) {
+            if (!(field.name in record)) {
+                if (field.required)
+                    throw new InvocationError(`missing required parameter(s): ${param.name}.${field.name}`);
+                continue;
+            }
+            const label = `${param.name}.${field.name}`;
+            const coerced = coerceType(record[field.name], field, label);
+            checkConstraints(coerced, field, label);
+        }
+    }
+}
 /**
  * Check one argument against its declared schema, raising a caller-safe error.
  *
@@ -16,23 +164,29 @@ import { InvocationError } from "./index-loader.js";
  * rather than being encoded into a URL.
  */
 export function coerce(value, param) {
+    const coerced = coerceType(value, param);
+    checkConstraints(coerced, param);
+    checkFields(coerced, param);
+    return coerced;
+}
+function coerceType(value, param, label = param.name) {
     const expected = param.type;
     if (expected === "object" || expected === "array") {
         // An opaque body object is passed through as given: the spec does not describe its
         // fields, so validating or reshaping it would mean inventing a contract.
         if (expected === "object" &&
             (typeof value !== "object" || value === null || Array.isArray(value))) {
-            throw new InvocationError(`'${param.name}' must be an object`);
+            throw new InvocationError(`'${label}' must be an object`);
         }
         if (expected === "array" && !Array.isArray(value)) {
-            throw new InvocationError(`'${param.name}' must be a list`);
+            throw new InvocationError(`'${label}' must be a list`);
         }
         return value;
     }
     if (expected === "integer" || expected === "number") {
         const parsed = Number(String(value).trim());
         if (!Number.isFinite(parsed)) {
-            throw new InvocationError(`'${param.name}' must be a number`);
+            throw new InvocationError(`'${label}' must be a number`);
         }
         return expected === "integer" ? Math.trunc(parsed) : parsed;
     }
@@ -44,13 +198,13 @@ export function coerce(value, param) {
             return true;
         if (["false", "0", "no"].includes(text))
             return false;
-        throw new InvocationError(`'${param.name}' must be true or false`);
+        throw new InvocationError(`'${label}' must be true or false`);
     }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));
         if (!allowed.includes(text)) {
-            throw new InvocationError(`'${param.name}' must be one of: ${allowed.join(", ")}`);
+            throw new InvocationError(`'${label}' must be one of: ${allowed.join(", ")}`);
         }
     }
     return text;

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

@@ -1,6 +1,12 @@
 /**
  * The tool surface: four discovery tools plus ONE invoke tool.
  *
+ * Discovery is deliberately two steps. `searchCapability` returns a shortlist — enough to
+ * CHOOSE — and `describeCapability` returns the contract for the one chosen. Parameters and
+ * response shapes are 86% of a full record and are needed once, not eight times: measured
+ * over eight queries, ~8.6k tokens a search becomes ~1.1k, and even describing every result
+ * still costs less than the single fat call did.
+ *
  * ONE invoke tool means one set of MCP annotations, so they describe the whole surface
  * honestly: it can write (not read-only) and it can never delete, because destructive
  * endpoints are refused before binding. Write consent therefore rests on `user_permission`

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

@@ -1,6 +1,12 @@
 /**
  * The tool surface: four discovery tools plus ONE invoke tool.
  *
+ * Discovery is deliberately two steps. `searchCapability` returns a shortlist — enough to
+ * CHOOSE — and `describeCapability` returns the contract for the one chosen. Parameters and
+ * response shapes are 86% of a full record and are needed once, not eight times: measured
+ * over eight queries, ~8.6k tokens a search becomes ~1.1k, and even describing every result
+ * still costs less than the single fat call did.
+ *
  * ONE invoke tool means one set of MCP annotations, so they describe the whole surface
  * honestly: it can write (not read-only) and it can never delete, because destructive
  * endpoints are refused before binding. Write consent therefore rests on `user_permission`
@@ -91,29 +97,12 @@ export function addCapabilityRegistryTools(server, deps, config) {
         : z.string();
     /** "tm, loadtesting" — for prose that has to name them. */
     const productList = productNames.join(", ") || "none loaded";
-    /**
-     * One line per product, for the ONE tool whose job is routing between them.
-     *
-     * Only listProducts carries the summaries. They are authored prose of unbounded length —
-     * tm's is 90 characters, loadtesting's is 470 — and a tool description is static context
-     * on every request, so repeating them across five tools would cost more than the round
-     * trip they save. Everywhere else the names alone are what a caller needs.
-     *
-     * Each summary is cut to its first sentence and capped, and the whole catalog is
-     * budgeted: past the budget the names still route, which is the part that matters.
-     */
-    const productCatalog = (() => {
-        const lines = productNames.map((name) => {
-            const summary = registry.index.products[name].summary.trim();
-            const firstSentence = summary.split(/(?<=\.)\s/)[0] ?? summary;
-            const trimmed = firstSentence.length > 130
-                ? `${firstSentence.slice(0, 127).trimEnd()}…`
-                : firstSentence;
-            return `${name} — ${trimmed.replace(/\.$/, "")}`;
-        });
-        const joined = lines.join("; ");
-        return joined.length <= 500 ? joined : productList;
-    })();
+    // NO PRODUCT CATALOG IN ANY DESCRIPTION. listProducts used to restate every product's
+    // trimmed summary in its own description — duplicating, as static context on every
+    // single request, the exact thing the tool returns when called. Authored summaries are
+    // also unbounded (loadtesting's runs to 470 characters) and change with the artifact,
+    // so the prose went stale on its own. The names still travel in the `product` enum,
+    // which is where a client can actually validate them.
     const transport = deps.transport || fetchTransport();
     const tools = {};
     /** Instrumentation in the house style, and never fatal to the call it wraps. */
@@ -125,9 +114,9 @@ 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. " +
-        "Start here when you do not know which product a task belongs to. " +
-        `This build carries ${productCatalog}.`, {}, {
+    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.", {}, {
         title: "List Capability Products",
         readOnlyHint: true,
         destructiveHint: false,
@@ -141,6 +130,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
             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.
+                //
+                // ~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,
@@ -148,27 +149,22 @@ export function addCapabilityRegistryTools(server, deps, config) {
             })),
         });
     });
-    tools.listEntities = server.tool("listEntities", "List the entities a product models (test case, folder, test plan, …). Use it to scope " +
-        "searchCapability, or to find the entity name describeEntity wants.", {
-        product: productArg().describe(`Which product to list entities for: ${productList}.`),
-    }, {
-        title: "List Product Entities",
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-    }, async ({ product }) => {
-        track("listEntities");
-        const bundle = registry.index.products[product];
-        if (!bundle)
-            return failed(`unknown product '${product}'`);
-        return ok({ product, entities: Object.keys(bundle.entities).sort() });
-    });
+    // listEntities WAS HERE, and is gone. It answered `{product, entities: [names]}` — a
+    // strict subset of what listProducts now returns for every product, and with the
+    // aliases missing. Keeping it would have meant two tools for one question, and a tool
+    // definition costs context on every request whether or not it is called, which is the
+    // entire reason this surface is five generic tools instead of 173 specific ones.
+    //
+    // One consequence to watch: listProducts now carries every product's vocabulary rather
+    // than one product's on request, so it grows with the number of products — roughly 1KB
+    // each. That is the right trade while routing is the problem it solves (you cannot
+    // choose between products by looking at one of them), but past a dozen products it may
+    // need a names-only default with aliases on request.
     tools.describeEntity = server.tool("describeEntity", "Describe one entity: what it is, what identifies it, what it relates to, and the " +
         "vocabulary the product uses for it. Read this before filtering or writing, because " +
         "ids and field values usually have to be resolved first.", {
         product: productArg().describe(`Which product the entity belongs to: ${productList}.`),
-        entity: z.string().describe("Entity name from listEntities."),
+        entity: z.string().describe("Entity name, as listProducts returns it."),
     }, {
         title: "Describe Entity",
         readOnlyHint: true,
@@ -196,20 +192,21 @@ export function addCapabilityRegistryTools(server, deps, config) {
         "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. " +
-        "Each result carries the capability's `name` — the handle you pass to " +
-        "invokeCapability — plus its `method` and `path` (use those two only when a result " +
-        "has no `name`), and its parameters grouped into path_params / query / body under " +
-        "the spec's own names. Pass them straight back, no renaming. `intent` says what it does, " +
-        "`mode` tells you whether it writes, `product` says which product owns it, and " +
-        "`responses` describes what a successful call returns, fully expanded. Results are " +
-        "ranked and capped, and `truncated` says when more matched. Search before invoking.", {
+        "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. " +
+        "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 " +
+        "a search. Results are ranked and capped, and `truncated` says when more matched.", {
         query: z
             .string()
             .describe("What you are trying to do, in plain language."),
         entity: z
             .string()
             .optional()
-            .describe("Restrict to one entity (see listEntities)."),
+            .describe("Restrict to one entity (listProducts names them)."),
         product: productArg()
             .optional()
             .describe(`Restrict to one product: ${productList}. Omit to search all of them.`),
@@ -218,21 +215,14 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .optional()
             .describe("Restrict to reads or writes. Omit to let the query decide."),
         limit: z.number().optional().describe("Max results (default 8)."),
-        include_responses: z
-            .enum(["success", "all", "none"])
-            .optional()
-            .describe("Which declared responses to expand: 'success' (default, the 2xx shape), 'all' " +
-            "(adds the error shapes — several times larger, and near-identical across " +
-            "endpoints), or 'none'."),
     }, {
         title: "Search Capabilities",
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async ({ query, entity, product, mode, limit, include_responses }) => {
+    }, async ({ query, entity, product, mode, limit }) => {
         track("searchCapability");
-        const selection = (include_responses || "success");
         const { hits, weak, top_matched, ...rest } = searchCapabilities(registry.index.products, query, {
             entity,
             product,
@@ -241,23 +231,28 @@ export function addCapabilityRegistryTools(server, deps, config) {
         });
         return ok({
             build_id: registry.buildId,
-            // Dereferenced HERE rather than in the artifact: the tables store each response and
-            // schema once and the capabilities name them, so the file stays a third of the size
-            // it would be inlined. Expanding on the way out means the caller never has to
-            // resolve a `{"$schema": "…"}` itself, and never sees one.
-            capabilities: hits.map(({ product: owner, capability }) => {
-                const responses = resolveResponses(registry.index.products[owner], capability, selection);
-                // The raw field is dropped, not merely overwritten: it holds `{"$response": …}`
-                // references, and spreading the capability would leak them straight through
-                // whenever the resolved value is absent.
-                const { responses: unresolved, ...rest } = capability;
-                void unresolved;
-                return {
-                    ...rest,
-                    product: owner,
-                    ...(responses ? { responses } : {}),
-                };
-            }),
+            // 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,
+                mode: capability.mode,
+                entity: capability.entity,
+                ...(capability.intent ? { intent: capability.intent } : {}),
+                ...(capability.guidance?.length
+                    ? { guidance: capability.guidance }
+                    : {}),
+            })),
             ...rest,
             // WHEN THE MATCH IS WEAK, HAND OVER THE VOCABULARY.
             //
@@ -281,7 +276,79 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 : {}),
         });
     });
-    tools.invokeCapability = server.tool("invokeCapability", "Call a capability returned by searchCapability or describeEntity. Pass `name` exactly " +
+    tools.describeCapability = server.tool("describeCapability", "The full contract for ONE capability you picked from searchCapability: its " +
+        "parameters grouped into path_params / query / body under the spec's own names, " +
+        "what it returns, and its declared response shapes fully expanded. Call this after " +
+        "search and before invokeCapability — search deliberately omits all of it, because " +
+        "it is only needed for the one capability you actually call. " +
+        "Identify it by `name`, exactly as search returned it; only when a result carries " +
+        "no `name` (some products publish none yet) pass `method` and `path` instead. " +
+        "Every parameter lists its type, whether it is required, its allowed values where " +
+        "the set is closed, and any limits the product declares — obey those before calling " +
+        "rather than discovering them from a rejected request.", {
+        name: z
+            .string()
+            .optional()
+            .describe("The capability's published name, exactly as searchCapability returned it."),
+        method: z
+            .string()
+            .optional()
+            .describe("HTTP method — only for capabilities returned without a `name`."),
+        path: z
+            .string()
+            .optional()
+            .describe("Path with {placeholders} intact — only for capabilities returned without a `name`."),
+        product: productArg()
+            .optional()
+            .describe(`Which product owns it (${productList}). searchCapability returns it on every ` +
+            "result; required only when two products share a name or a path."),
+        include_responses: z
+            .enum(["success", "all", "none"])
+            .optional()
+            .describe("Which declared responses to expand: 'success' (default, the 2xx shape), 'all' " +
+            "(adds the error shapes — several times larger, and near-identical across " +
+            "endpoints), or 'none'."),
+    }, {
+        title: "Describe Capability",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async (input) => {
+        track("describeCapability");
+        try {
+            // The same two handles as invokeCapability, resolved the same way, so a name that
+            // describes is a name that invokes. Divergence here would be its own bug class.
+            if (!input.name && !(input.method && input.path)) {
+                return failed("pass `name` — or, for a capability returned without one, both `method` and " +
+                    "`path`, exactly as searchCapability returned them");
+            }
+            const { product: owner, capability } = input.name
+                ? registry.byNameLookup(input.name, input.product)
+                : registry.byEndpointLookup(input.method, input.path, input.product);
+            const selection = (input.include_responses ||
+                "success");
+            const responses = resolveResponses(registry.index.products[owner], capability, selection);
+            // 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;
+            void unresolved;
+            return ok({
+                build_id: registry.buildId,
+                product: owner,
+                ...contract,
+                ...(responses ? { responses } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof InvocationError)
+                return failed(error.message);
+            logger.error("describeCapability failed: %s", error instanceof Error ? error.message : String(error));
+            return failed("that capability could not be described");
+        }
+    });
+    tools.invokeCapability = server.tool("invokeCapability", "Call a capability whose contract you have from describeCapability. Pass `name` exactly " +
         "as given — that is the handle. Only when a result carries no `name` (some products " +
         "do not publish them yet) pass `method` and `path` instead, exactly as returned. " +
         "Arguments go in path_params / query / body under the spec's own names. One call " +

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

@@ -66,12 +66,13 @@ export interface SearchResult {
      * separates them is how little the match is worth.
      */
     top_matched: number;
+    /** `top_matched` as a fraction of a perfect match — the corpus-independent form. */
+    coverage: number;
     weak: boolean;
 }
 /** One entity's caller-facing vocabulary: what it is called, and what else it is called. */
 export interface VocabularyEntry {
     entity: string;
-    title?: string;
     aliases?: string[];
 }
 /**
@@ -83,10 +84,15 @@ 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, deliberately. They are the vocabulary map — 19 entities in ~1.5KB, against a
- * response that is routinely 38KB. 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
+ * 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.
+ *
+ * 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
+ * change and is still under a thousand tokens — far less than one wrong invoke — so this
+ * is budgeted in bytes rather than as a fraction of a baseline that now moves.
  */
 export declare function vocabularyOf(products: Record<string, ProductIndex>, only?: string): Record<string, VocabularyEntry[]>;
 export declare function searchCapabilities(products: Record<string, ProductIndex>, query?: string, options?: {