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

package/capability/tm.capability-index.json

@@ -1,9 +1,9 @@
 {
   "schema_version": 1,
-  "version": "1.5",
-  "build_id": "bd02ae3b_2026-09-10T11:51:51Z",
+  "version": "1.6",
+  "build_id": "2d3d82f8_2026-09-11T09:37:38Z",
   "tm": {
-    "summary": "BrowserStack Test Management API (v1 — the SSO/OAuth app API, session-authenticated).",
+    "summary": "BrowserStack Test Management: author and organise test cases, plan and track their execution, and report on the results. Everything is scoped to a project, which owns the folders, cases, runs, plans and reports beneath it. Search and filter cases; create and update cases, runs and plans; record results; bulk edit, move, copy, archive and delete; restructure folders; manage tags and custom-field definitions; assign, clone and close runs; review AI duplicate recommendations; read the activity feed and a case's version history; and create, schedule and download reports. Cases are authored and their outcomes recorded here, but tests are not RUN here: execution happens in your own runner or another BrowserStack product. Renaming and deleting a project are not exposed. Destructive capabilities exist and always need explicit human approval.",
     "capabilities": [
       {
         "name": "assign_test_run_owner",
@@ -18556,7 +18556,7 @@
             },
             "selection": {
               "type": "object",
-              "description": "the primary project's persisted folder-structured test-case selection (with select_all / per-folder flags + unique_test_case_count), in the same shape as the test-run edit/selection endpoint. `{}` when the report has no saved selection for the primary project. Used by the Edit dialog to re-check saved test cases (including folder/project-level select_all, which the flat ids cannot represent).",
+              "description": "The primary project's persisted folder-structured test-case selection (with select_all / per-folder flags + unique_test_case_count), in the same shape as the test-run edit/selection endpoint. `{}` when the report has no saved selection for the primary project. Used by the Edit dialog to re-check saved test cases (including folder/project-level select_all, which the flat ids cannot represent).",
               "example": {
                 "select_all": false,
                 "folders": {
@@ -18573,7 +18573,7 @@
             },
             "shared_selection": {
               "type": "object",
-              "description": "per-project folder-structured selection for the report's non-primary projects, keyed by project id ({ \"<project_id>\": <selection> }). Present only for cross-project Test Case Activity reports; `{}` otherwise.",
+              "description": "Per-project folder-structured selection for the report's non-primary projects, keyed by project id ({ \"<project_id>\": <selection> }). Present only for cross-project Test Case Activity reports; `{}` otherwise.",
               "example": {
                 "10209": {
                   "select_all": true,
@@ -19455,6 +19455,7 @@
       "activity": {
         "entity": "activity",
         "title": "Activity feed (audit trail)",
+        "description": "Group-wide audit trail of who changed what, on which entity, and when.",
         "aliases": [
           "activity",
           "activities",
@@ -19500,6 +19501,7 @@
       "attachment": {
         "entity": "attachment",
         "title": "Attachments",
+        "description": "A file hanging off a parent test case or test result.",
         "aliases": [
           "attachment",
           "file",
@@ -19535,6 +19537,7 @@
       "configuration": {
         "entity": "configuration",
         "title": "Configurations",
+        "description": "An operating system, browser or device combination that a test run executes against.",
         "aliases": [
           "config",
           "configuration",
@@ -19561,6 +19564,7 @@
       "custom_field": {
         "entity": "custom_field",
         "title": "Custom fields & system fields",
+        "description": "A user-defined field on test cases, results or plans, alongside the built-in system fields.",
         "aliases": [
           "custom field",
           "custom fields",
@@ -19612,6 +19616,7 @@
       "dataset": {
         "entity": "dataset",
         "title": "Dataset",
+        "description": "A named table of variables and rows that drives data-driven execution of a test case.",
         "aliases": [
           "datasets",
           "data-driven-data",
@@ -19648,6 +19653,7 @@
       "duplicate": {
         "entity": "duplicate",
         "title": "Duplicate recommendation (AI dedupe)",
+        "description": "A machine-suggested pair of near-identical test cases, for a human to review and merge.",
         "aliases": [
           "duplicate",
           "duplicates",
@@ -19687,6 +19693,7 @@
       "exploratory_session": {
         "entity": "exploratory_session",
         "title": "Exploratory session",
+        "description": "An unscripted, charter-driven testing session and the observations recorded during it.",
         "aliases": [
           "session",
           "exploratory",
@@ -19739,6 +19746,7 @@
       "filter": {
         "entity": "filter",
         "title": "Saved filter view",
+        "description": "A saved, named set of filter conditions a user can reapply to a list view.",
         "aliases": [
           "filter",
           "filters",
@@ -19779,6 +19787,7 @@
       "folder": {
         "entity": "folder",
         "title": "Folder",
+        "description": "A container organising test cases inside a project; folders nest to form a tree.",
         "aliases": [
           "dir",
           "directory"
@@ -19819,6 +19828,7 @@
       "project": {
         "entity": "project",
         "title": "Project",
+        "description": "The top-level container that owns every folder, test case, run, plan and report.",
         "aliases": [
           "pr",
           "workspace"
@@ -19875,6 +19885,7 @@
       "report": {
         "entity": "report",
         "title": "Report",
+        "description": "A saved, optionally scheduled analytics view over a project's test data.",
         "aliases": [
           "reports",
           "scheduled-report",
@@ -19931,6 +19942,7 @@
       "result": {
         "entity": "result",
         "title": "Result",
+        "description": "The recorded outcome of one test case in one run: its status, and who set it.",
         "aliases": [
           "outcome",
           "execution-result",
@@ -19968,6 +19980,7 @@
       "shared_step": {
         "entity": "shared_step",
         "title": "Shared step",
+        "description": "A reusable block of test steps that many test cases embed by reference.",
         "aliases": [
           "shared step",
           "shared steps",
@@ -19999,6 +20012,7 @@
       "tag": {
         "entity": "tag",
         "title": "Tag",
+        "description": "A free-text label on a test case, run or plan, used to group and filter them.",
         "aliases": [
           "tags",
           "label",
@@ -20040,6 +20054,7 @@
       "test_case": {
         "entity": "test_case",
         "title": "Test case",
+        "description": "The unit of test logic: title, preconditions, steps and expected results.",
         "aliases": [
           "tc",
           "case",
@@ -20111,6 +20126,7 @@
       "test_plan": {
         "entity": "test_plan",
         "title": "Test plan (and sub-plan)",
+        "description": "A container grouping several test runs, typically for one release or milestone.",
         "aliases": [
           "tp",
           "plan",
@@ -20154,7 +20170,7 @@
           "The read detail has NO data wrapper: the plan sits under a top-level test_plan key, and test_plan.identifier is the TP-NNN / STP-NNN.",
           "Sub-plans are HIDDEN by default in the list. Without include_sub_plans=true you see only top-level plans, so a sub-plan the user named will look missing.",
           "name IS REQUIRED ON EVERY PLAN UPDATE, including one that only touches test_runs. Omit it and the call is rejected with 400 {success: false, error: 'Invalid Update Params'} however valid the rest of the body is — the server's edit branch is gated on name being present. Read the plan first and echo its current name back unchanged. Only a pure plan_status transition and a reviewers-only edit are exempt. Verified live: {test_plan: {test_runs: [198]}} 400s; adding name makes the identical call succeed.",
-          "Run ids in test_runs are the INTEGER uuid from a run read — NOT the run's id field, which is the TR-NNN string on every run endpoint (list, plan's run list, single detail alike). Identifiers are forwarded to the backing service uncoerced and fail upstream (observed 502 Upstream backing-service error). Take uuid, never id.",
+          "Run ids in test_runs are the INTEGER uuid from a run read — NOT the run's id field, which is the TR-NNN string on every run endpoint (list, plan's run list, single detail alike). Identifiers are forwarded to the backing service uncoerced and fail upstream (observed 502 Upstream service error). Take uuid, never id.",
           "Linking a run MOVES it: a run belongs to at most one plan, so linking silently unlinks it from the plan that held it, with nothing in the 200 to say so. Read the runs' current membership first and tell the user which plans will lose runs. Verified live.",
           "test_runs accepts an id array OR a bulk-selection object {select_all, de_selected_ids, search_query}. select_all means 'the newest active runs', NOT 'everything matching' — and `filters` is accepted but SILENTLY IGNORED, so a filtered select_all links the whole recent set. Narrow with search_query (name/identifier substring) or send explicit ids. Verified live.",
           "bulk-archive / bulk-retrieve go ASYNC above the bulk threshold and return {success, async: true, unique_id} — the plans are NOT changed yet. Re-read to confirm; see async-jobs.",
@@ -20165,6 +20181,7 @@
       "test_run": {
         "entity": "test_run",
         "title": "Test run",
+        "description": "One execution cycle over a fixed set of test cases.",
         "aliases": [
           "tr",
           "run",
@@ -20221,6 +20238,7 @@
       "user": {
         "entity": "user",
         "title": "User",
+        "description": "A member with access to a project: who you assign a case to, or set as an owner.",
         "aliases": [
           "users",
           "member",
@@ -20257,6 +20275,7 @@
       "version": {
         "entity": "version",
         "title": "Test case version",
+        "description": "A point-in-time snapshot of a test case, for viewing or restoring an earlier revision.",
         "aliases": [
           "history",
           "histories",

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

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

@@ -145,6 +145,36 @@ export function termForms(term) {
         add(term.slice(0, -1));
     return forms;
 }
+/**
+ * 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 function singular(word) {
+    if (word.endsWith("ss"))
+        return word;
+    // histories -> history. Without this the alias `histories` and the entity word
+    // `history` are two unrelated terms, which is the same defect in another spelling.
+    if (word.endsWith("ies") && word.length > 4)
+        return `${word.slice(0, -3)}y`;
+    // Only where the `e` is genuinely inserted. `s` is NOT in this set: `cases` ends in
+    // `ses` and is `case` + `s`, not `cas` + `es`, and no rule can tell it from `statuses`
+    // by suffix alone — so the commoner reading wins and `-s` is stripped below.
+    if (/(?:ch|sh|x|z)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.endsWith("s") && word.length > 3)
+        return word.slice(0, -1);
+    return word;
+}
 /** A haystack as one lowercased, space-separated string, ready for containment tests. */
 function haystack(text) {
     return terms(text).join(" ");
@@ -436,46 +466,68 @@ function score(capability, wanted, weights, aliases, hint, plural) {
 const WEAK_COVERAGE = 0.25;
 /** The heaviest field, and so the yardstick a perfect match is measured against. */
 const IDENTITY_WEIGHT = 6;
-/** Slots a matching product is guaranteed, before the rest of the page fills by rank. */
-const PRODUCT_FLOOR = 2;
 /**
- * Fill the page by rank, but never let one product's SIZE shut another out entirely.
- *
- * Scores are comparable across products — rarity spans the whole corpus by design — but
- * the number of chances to score is not: tm has 173 capabilities to Load Testing's 20. On
- * a query using words both products share ("test", "config", "tag"), tm simply has more
- * entries near the top and takes the page. Measured before this: "add a tag to xyz test"
- * returned tm tm LT tm tm, and an agent reading the first row went to the wrong product.
- *
- * So each product that matched at all is guaranteed a couple of slots, and everything else
- * is still strict rank order. This does NOT reorder anything or touch scoring — the best
- * hit stays the best hit — it only refuses to let a product be invisible because it is
- * small. The cost when a query really is single-product is a row or two of another
- * product's shortlist, which since the split is a few hundred bytes.
+ * 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.
  */
-function withEveryProductRepresented(scored, limit) {
-    if (scored.length <= limit)
-        return scored;
-    const products = new Set(scored.map((s) => s.product));
-    if (products.size < 2)
-        return scored.slice(0, limit);
-    const taken = new Set();
-    // Reserve first, so a product near the bottom of the ranking still gets its footing.
-    for (const product of products) {
-        for (const hit of scored
-            .filter((s) => s.product === product)
-            .slice(0, PRODUCT_FLOOR)) {
-            if (taken.size < limit)
-                taken.add(hit);
+export function ambiguousProducts(products, query) {
+    const none = { products: [], terms: [] };
+    if (terms(query).length === 0)
+        return none;
+    /**
+     * One spelling per word, so a plural cannot masquerade as a different term.
+     *
+     * Both halves need it. On the QUERY side, the entry is `project` and the user types
+     * "list all projects" — the reported case, which exact containment missed. On the
+     * VOCABULARY side the same fold is what keeps the answer honest: tm lists both `report`
+     * and `reports` as aliases, and treating them as two entries made `reports` look
+     * tm-exclusive, so "show me the report" read as settled when both products claim it.
+     */
+    const fold = (text) => terms(text).map(singular).join(" ");
+    const asked_ = ` ${fold(query || "")} `;
+    const owners = new Map();
+    for (const [product, entries] of Object.entries(vocabularyOf(products))) {
+        for (const entry of entries) {
+            for (const word of [entry.entity, ...(entry.aliases ?? [])]) {
+                const key = fold(String(word));
+                if (!key)
+                    continue;
+                if (!owners.has(key))
+                    owners.set(key, new Set());
+                owners.get(key).add(product);
+            }
         }
     }
-    for (const hit of scored) {
-        if (taken.size >= limit)
-            break;
-        taken.add(hit);
+    const shared = new Map();
+    for (const [key, claimants] of owners) {
+        if (!asked_.includes(` ${key} `))
+            continue;
+        // A term only one product claims decides the query outright.
+        if (claimants.size < 2)
+            return none;
+        shared.set(key, claimants);
     }
-    // Emit in the original ranked order: the floor decides WHO appears, never in what order.
-    return scored.filter((hit) => taken.has(hit));
+    if (shared.size === 0)
+        return none;
+    const claimed = new Set();
+    for (const claimants of shared.values())
+        for (const product of claimants)
+            claimed.add(product);
+    return { products: [...claimed].sort(), terms: [...shared.keys()].sort() };
 }
 /**
  * The product's vocabulary, for a caller whose words are not the product's words.
@@ -486,10 +538,14 @@ function withEveryProductRepresented(scored, limit) {
  * 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
@@ -504,8 +560,12 @@ export function vocabularyOf(products, only) {
         const entries = [];
         for (const [entity, doc] of Object.entries(bundle.entities || {})) {
             const aliases = (doc.aliases || []);
+            const description = doc.description;
             entries.push({
                 entity,
+                // Before the aliases, because it is what the reader needs first: what the thing
+                // is, then what else it is called.
+                ...(description ? { description } : {}),
                 ...(aliases.length ? { aliases } : {}),
             });
         }
@@ -575,7 +635,9 @@ export function searchCapabilities(products, query, options = {}) {
     const perfect = weights.reduce((sum, w) => sum + IDENTITY_WEIGHT * w, 0);
     const coverage = perfect > 0 ? topMatched / perfect : 1;
     return {
-        hits: withEveryProductRepresented(scored, limit).map(({ product, capability }) => ({ product, capability })),
+        hits: scored
+            .slice(0, limit)
+            .map(({ product, capability }) => ({ product, capability })),
         truncated: scored.length > limit,
         total_matched: scored.length,
         top_matched: topMatched,

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

@@ -148,6 +148,20 @@ export interface Capability {
 }
 export interface EntityDoc {
     title?: string;
+    /**
+     * One line saying what this entity IS. Rides on `listProducts`, next to the aliases.
+     *
+     * Aliases route; they do not define. `version -> history, revision, version-history`
+     * tells a caller which words land here and nothing about whether that is the versioning
+     * of a test case or of a project. Without this line the only way to find out is
+     * `describeEntity`, once per entity — 19 calls at ~1.4KB for tm, against ~1.6KB to
+     * answer it for all of them at once.
+     *
+     * Capped at 140 characters by the build, and dropped rather than truncated when longer.
+     * Often absent: a product that has not authored these emits none (loadtesting has 0 of
+     * 9 today), and absence means "unwritten", never an error.
+     */
+    description?: string;
     aliases?: string[];
     id_convention?: string;
     parents?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.5.0-beta.15",
+  "version": "1.5.0-beta.16",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",