@browserstack/mcp-server 2.2.2-beta.1 → 2.2.2-beta.2

package/dist/tools/accessibility.js

@@ -305,8 +305,7 @@ export default function addAccessibilityTools(server, config) {
             return handleMCPError("createAccessibilityAuthConfig", server, config, error);
         }
     });
-    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Retrieve an existing authentication configuration by ID." +
-        NEEDS_A11Y_CONFIG_ID, {
+    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Get an accessibility auth config by ID." + NEEDS_A11Y_CONFIG_ID, {
         configId: z.number().describe("ID of the auth configuration to retrieve"),
     }, {
         title: "Get Accessibility Auth Config",
@@ -317,7 +316,7 @@ export default function addAccessibilityTools(server, config) {
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
-    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results." +
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch a completed scan's accessibility issues; page with `cursor`." +
         NEEDS_A11Y_SCAN_ID, {
         scanId: z
             .string()

package/dist/tools/appautomate-utils/appium-sdk/constants.d.ts

@@ -21,7 +21,7 @@ export declare const MobileDeviceSchema: z.ZodObject<{
     deviceName: z.ZodString;
     osVersion: z.ZodString;
 }, z.core.$strip>;
-export declare const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead.";
+export declare const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up the App Automate SDK for Appium tests. For pre-built Espresso or XCUITest suites use runAppTestsOnBrowserStack.";
 export declare const SETUP_APP_AUTOMATE_SCHEMA: {
     detectedFramework: z.ZodEnum<typeof AppSDKSupportedFrameworkEnum>;
     detectedTestingFramework: z.ZodEnum<typeof AppSDKSupportedTestingFrameworkEnum>;

package/dist/tools/appautomate-utils/appium-sdk/constants.js

@@ -31,14 +31,14 @@ export const MobileDeviceSchema = z.object({
     osVersion: z.string().describe("OS version, e.g. '14', '16', '17', 'latest'"),
 });
 // Tool description and schema for setupBrowserStackAppAutomateTests
-export const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead.";
+export const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up the App Automate SDK for Appium tests. For pre-built Espresso or XCUITest suites use runAppTestsOnBrowserStack.";
 export const SETUP_APP_AUTOMATE_SCHEMA = {
     detectedFramework: z
         .nativeEnum(AppSDKSupportedFrameworkEnum)
         .describe("The mobile automation framework configured in the project. Example: 'appium'"),
     detectedTestingFramework: z
         .nativeEnum(AppSDKSupportedTestingFrameworkEnum)
-        .describe("The testing framework used in the project. Be precise with framework selection Example: 'testng', 'behave', 'pytest', 'robot'"),
+        .describe("Test framework in the project, e.g. testng, behave, pytest, robot."),
     detectedLanguage: z
         .nativeEnum(AppSDKSupportedLanguageEnum)
         .describe("The programming language used in the project. Supports Java and C#. Example: 'java', 'csharp'"),
@@ -46,7 +46,7 @@ export const SETUP_APP_AUTOMATE_SCHEMA = {
         .array(MobileDeviceSchema)
         .max(3)
         .default([])
-        .describe("Tuples describing target mobile devices. Add device only when user asks explicitly for it. Defaults to [] . Example: [['android', 'Samsung Galaxy S24', '14'], ['ios', 'iPhone 15', '17']]"),
+        .describe("Only devices the user asked for, e.g. [['android', 'Samsung Galaxy S24', '14']]."),
     appPath: z
         .string()
         .describe("Path to the mobile app file (.apk for Android, .ipa for iOS). Can be a local file path or a BrowserStack app URL (bs://)"),

package/dist/tools/appautomate-utils/native-execution/constants.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AppTestPlatform } from "./types.js";
-export declare const RUN_APP_AUTOMATE_DESCRIPTION = "Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.";
+export declare const RUN_APP_AUTOMATE_DESCRIPTION = "Run pre-built Espresso (Android) or XCUITest (iOS) suites on BrowserStack by upload. Not for Appium: use setupBrowserStackAppAutomateTests.";
 export declare const MobileDeviceSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         android: "android";

package/dist/tools/appautomate-utils/native-execution/constants.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AppTestPlatform } from "./types.js";
-export const RUN_APP_AUTOMATE_DESCRIPTION = `Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.`;
+export const RUN_APP_AUTOMATE_DESCRIPTION = `Run pre-built Espresso (Android) or XCUITest (iOS) suites on BrowserStack by upload. Not for Appium: use setupBrowserStackAppAutomateTests.`;
 export const MobileDeviceSchema = z.object({
     platform: z
         .enum(["android", "ios"])
@@ -13,31 +13,15 @@ export const MobileDeviceSchema = z.object({
 export const RUN_APP_AUTOMATE_SCHEMA = {
     appPath: z
         .string()
-        .describe("Path to your application file:\n" +
-        "If in development IDE directory:\n" +
-        "• For Android: 'gradle assembleDebug'\n" +
-        "• For iOS:\n" +
-        "  xcodebuild clean -scheme YOUR_SCHEME && \\\n" +
-        "  xcodebuild archive -scheme YOUR_SCHEME -configuration Release -archivePath build/app.xcarchive && \\\n" +
-        "  xcodebuild -exportArchive -archivePath build/app.xcarchive -exportPath build/ipa -exportOptionsPlist exportOptions.plist\n\n" +
-        "If in other directory, provide existing app path.\n" +
-        "The resolved file must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
+        .describe("Built .apk/.ipa inside MCP_UPLOAD_BASE_DIR (gradle assembleDebug, or xcodebuild archive and export)."),
     testSuitePath: z
         .string()
-        .describe("Path to your test suite file:\n" +
-        "If in development IDE directory:\n" +
-        "• For Android: 'gradle assembleAndroidTest'\n" +
-        "• For iOS:\n" +
-        "  xcodebuild test-without-building -scheme YOUR_SCHEME -destination 'generic/platform=iOS' && \\\n" +
-        "  cd ~/Library/Developer/Xcode/DerivedData/*/Build/Products/Debug-iphonesimulator/ && \\\n" +
-        "  zip -r Tests.zip *.xctestrun *-Runner.app\n\n" +
-        "If in other directory, provide existing test file path.\n" +
-        "The resolved file must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
+        .describe("Built suite inside MCP_UPLOAD_BASE_DIR (gradle assembleAndroidTest, or zipped .xctestrun + Runner.app)."),
     devices: z
         .array(MobileDeviceSchema)
         .max(3)
         .default([])
-        .describe("Tuples describing target mobile devices. Add device only when user asks explicitly for it. Defaults to [] . Example: [['android', 'Samsung Galaxy S24', '14'], ['ios', 'iPhone 15', '17']]"),
+        .describe("Only devices the user asked for, e.g. [['android', 'Samsung Galaxy S24', '14']]."),
     project: z
         .string()
         .optional()

package/dist/tools/appautomate.js

@@ -194,10 +194,10 @@ async function runAppTestsOnBrowserStack(args, config) {
 }
 export default function addAppAutomationTools(server, config) {
     const tools = {};
-    tools.takeAppScreenshot = server.tool("takeAppScreenshot", "Use this tool to take a screenshot of an app running on a BrowserStack device. This is useful for visual testing and debugging.", {
+    tools.takeAppScreenshot = server.tool("takeAppScreenshot", "Take a screenshot of an app running on a BrowserStack device.", {
         desiredPhone: z
             .string()
-            .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20'. Always ask the user for the device they want to use."),
+            .describe("Exact device name, e.g. 'iPhone 15 Pro Max'. Ask the user."),
         desiredPlatformVersion: z
             .string()
             .describe("The platform version to run the app on. Use 'latest' or 'oldest' for dynamic resolution."),
@@ -206,7 +206,7 @@ export default function addAppAutomationTools(server, config) {
             .describe("Platform to run the app on. Either 'android' or 'ios'."),
         appPath: z
             .string()
-            .describe("The path to the .apk or .ipa file. Required for app installation. Must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
+            .describe("Local .apk/.ipa path inside MCP_UPLOAD_BASE_DIR."),
     }, {
         title: "Take App Screenshot",
         readOnlyHint: false,

package/dist/tools/applive.js

@@ -54,19 +54,19 @@ export async function startAppLiveSession(args, config) {
 }
 export default function addAppLiveTools(server, config) {
     const tools = {};
-    tools.runAppLiveSession = server.tool("runAppLiveSession", "Use this tool when user wants to manually check their app on a particular mobile device using BrowserStack's cloud infrastructure. Can be used to debug crashes, slow performance, etc.", {
+    tools.runAppLiveSession = server.tool("runAppLiveSession", "Open an app on a real mobile device in App Live for a manual check or crash debugging.", {
         desiredPhone: z
             .string()
-            .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20' or 'Google Pixel 6'. Always ask the user for the device they want to use, do not assume it. "),
+            .describe("Exact device name, e.g. 'iPhone 15 Pro Max'. Ask the user; never assume."),
         desiredPlatformVersion: z
             .string()
-            .describe("Specifies the platform version to run the app on. For example, use '12.0' for Android or '16.0' for iOS. If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'."),
+            .describe("Version number, or 'latest' / 'oldest'."),
         desiredPlatform: z
             .enum(["android", "ios"])
             .describe("Which platform to run on, examples: 'android', 'ios'. Set this based on the app path provided."),
         appPath: z
             .string()
-            .describe("The path to the .ipa or .apk file to install on the device. Always ask the user for the app path, do not assume it. Must be located inside the directory set in MCP_UPLOAD_BASE_DIR."),
+            .describe("Local .apk/.ipa path inside MCP_UPLOAD_BASE_DIR. Ask the user; never assume."),
     }, {
         title: "Run App Live Session",
         readOnlyHint: false,

package/dist/tools/ask-browserstack/register.js

@@ -53,19 +53,12 @@ const DESCRIPTION =
 // tool that is not enabled for the account cannot do the job at all — so "there is a
 // per-account gate, fall back to the individual tools" is the most useful thing to say
 // first. Parenthesised so it reads as a status note, not as the tool's purpose.
-"(Alpha, limited availability. Enabled per account and per product; if it is not enabled " +
-    "the call returns an entitlement error, nothing runs, and you should complete the task " +
-    "with the individual tools instead. To request access, the user should contact their " +
-    "BrowserStack account owner.) " +
-    "Use this when no other BrowserStack tool here fits the task, or when the ones you tried " +
-    "did not get you there. Prefer a specific tool whenever one fits: it is faster and more " +
-    "predictable than handing the job to an agent. " +
-    "Otherwise, describe what you want in plain language and BrowserStack's agent decides " +
-    "which calls to make, then returns its answer plus the steps it took. Anything that would " +
-    "change data pauses and asks you to confirm it first; deletes are refused outright. " +
-    "Put that confirmation to the user and answer with what THEY say — never decide on " +
-    "their behalf. If it cannot be put to anyone, the run is read-only and everything it " +
-    "wanted to change comes back in `needs_approval` instead. One task per call.";
+"(Alpha, limited availability. If not enabled it returns an entitlement error; complete " +
+    "the task with the individual tools instead.) Use this when no other BrowserStack tool " +
+    "here fits, or when the ones you tried did not get you there. Prefer a specific tool " +
+    "whenever one fits. Describe the task in plain language. A data change asks you to " +
+    "confirm first: put it to the user, never decide for them; deletes are refused " +
+    "outright. One task per call.";
 /**
  * `isError` marks a call that FAILED, not one that was refused.
  *

package/dist/tools/automate-utils/fetch-screenshots.d.ts

@@ -1,9 +1,6 @@
 import { SessionType } from "../../lib/constants.js";
 import { BrowserStackConfig } from "../../lib/types.js";
-export declare function parseScreenshotUrls(text: string): string[];
-export type Screenshot = {
+export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<{
     url: string;
     base64: string;
-    mimeType: string;
-};
-export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<Screenshot[]>;
+}[]>;

package/dist/tools/automate-utils/fetch-screenshots.js

@@ -20,68 +20,28 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
     const text = typeof response.data === "string"
         ? response.data
         : JSON.stringify(response.data);
-    return parseScreenshotUrls(text);
-}
-const LOG_PREFIX = String.raw `^\d{4}-\d{2}-\d{2} \d{1,2}:\d{1,2}:\d{1,2}:\d{1,3} `;
-const LINE_TYPE_PATTERN = new RegExp(`${LOG_PREFIX}([A-Z_]+) `);
-const SCREENSHOT_REQUEST_PATTERN = new RegExp(String.raw `${LOG_PREFIX}REQUEST \[[^\]]+\] GET /session/[^/\s]+/screenshot(\s|$)`);
-const RESPONSE_VALUE_PATTERN = new RegExp(String.raw `${LOG_PREFIX}RESPONSE \{"value"\s*:\s*"(https://[^"]+)"`);
-const DEBUG_SCREENSHOT_PATTERN = new RegExp(String.raw `${LOG_PREFIX}DEBUG (https://\S+)$`);
-const TRUSTED_HOST_PATTERN = /(^|\.)browserstack\.com$|\.s3([.-][a-z0-9-]+)*\.amazonaws\.com$|\.backblazeb2\.com$/;
-function isTrustedScreenshotUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === "https:" && TRUSTED_HOST_PATTERN.test(url.hostname);
-    }
-    catch {
-        return false;
-    }
-}
-export function parseScreenshotUrls(text) {
     const urls = [];
-    const lines = text.split("\n").map((line) => line.trimEnd());
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const debugMatch = line.match(DEBUG_SCREENSHOT_PATTERN);
-        if (debugMatch) {
-            urls.push(debugMatch[1]);
-            continue;
-        }
-        if (!SCREENSHOT_REQUEST_PATTERN.test(line)) {
-            continue;
-        }
-        for (let j = i + 1; j < lines.length; j++) {
-            const lineType = lines[j].match(LINE_TYPE_PATTERN)?.[1];
-            if (lineType === "REQUEST") {
-                break;
-            }
-            if (lineType === "RESPONSE") {
-                const valueMatch = lines[j].match(RESPONSE_VALUE_PATTERN);
-                if (valueMatch) {
-                    urls.push(valueMatch[1]);
-                }
-                break;
+    const SCREENSHOT_PATTERN = /REQUEST.*GET.*\/screenshot/;
+    const RESPONSE_VALUE_PATTERN = /"value"\s*:\s*"([^"]+)"/;
+    // Split logs into lines and process them
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length - 1; i++) {
+        const currentLine = lines[i];
+        const nextLine = lines[i + 1];
+        if (SCREENSHOT_PATTERN.test(currentLine)) {
+            const match = nextLine.match(RESPONSE_VALUE_PATTERN);
+            if (match && match[1]) {
+                urls.push(match[1]);
             }
         }
     }
-    return [...new Set(urls)].filter(isTrustedScreenshotUrl);
-}
-function detectImageMimeType(buffer) {
-    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
-        return "image/jpeg";
-    }
-    return "image/png";
+    return urls;
 }
 async function fetchAndCompress(url) {
     const response = await apiClient.get({ url, responseType: "arraybuffer" });
     // Axios returns response.data as a Buffer for binary data
-    const buffer = Buffer.from(response.data);
-    const base64 = await maybeCompressBase64(buffer.toString("base64"));
-    return {
-        url,
-        base64,
-        mimeType: detectImageMimeType(Buffer.from(base64, "base64")),
-    };
+    const base64 = Buffer.from(response.data).toString("base64");
+    return { url, base64: await maybeCompressBase64(base64) };
 }
 //Converts screenshot URLs to base64 encoded images
 async function convertUrlsToBase64(urls) {

package/dist/tools/automate.js

@@ -14,7 +14,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
                 content: [
                     {
                         type: "text",
-                        text: "No screenshots found in the session logs. Run with browserstack.debug: true to capture visual-log screenshots.",
+                        text: "No screenshots found in the session or some unexpected error occurred",
                     },
                 ],
                 isError: true,
@@ -23,7 +23,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
         const results = screenshots.map((screenshot, index) => ({
             type: "image",
             data: screenshot.base64,
-            mimeType: screenshot.mimeType,
+            mimeType: "image/png",
             _meta: { url: screenshot.url, index: index + 1 },
         }));
         return {

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

@@ -189,24 +189,11 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return failed(message, extra);
     };
-    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. " +
-        "ALWAYS pass the user's request, in their own words, as `query`: the answer then " +
-        "says outright whether the products clash over the words in it. WHEN IT REPORTS A " +
-        "CLASH — two products claiming the same word for different things — ASK THE USER " +
-        "WHICH PRODUCT THEY MEAN AND WAIT FOR THEIR ANSWER BEFORE SEARCHING OR INVOKING " +
-        "ANYTHING. The response carries the question to put to them and what the shared " +
-        "word means in each product. Choosing for them, or searching each product in turn " +
-        "and merging the results, is the failure this call exists to prevent.", {
+    tools.listProducts = server.tool("listProducts", "List BrowserStack products and their entities. START HERE: searchCapability needs a product name from this. Pass the user's request as `query`; if it reports a clash, ask the user which product they mean and wait. Never pick for them or merge products.", {
         query: z
             .string()
             .optional()
-            .describe("The user's request, in their own words. With it the response carries a " +
-            "`routing` block saying whether the products share the vocabulary this " +
-            "request uses — and, when they do, the question to put to the user before " +
-            "searching either product."),
+            .describe("The user's request, in their own words; enables clash detection."),
     }, {
         title: "List Capability Products",
         readOnlyHint: true,
@@ -349,9 +336,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
     // 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.", {
+    tools.describeEntity = server.tool("describeEntity", "Describe an entity: identifiers, relations and product vocabulary. Read before filtering or writing; ids often need resolving first.", {
         product: productArg().describe(`Which product the entity belongs to: ${productList}.`),
         entity: z.string().describe("Entity name, as listProducts returns it."),
     }, {
@@ -371,38 +356,10 @@ 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, within ONE product. " +
-        "CALL listProducts FIRST, passing the user's request as its `query`: it names the " +
-        "products, says whether they clash over the words in that request, and gives you " +
-        "the question to ask when they do. You need it anyway — `product` here takes a name " +
-        "exactly as listProducts spells it. Where two products use the same word for " +
-        "different things, ask the USER and wait for an answer 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 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`, `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. " +
-        "TO SEE EVERYTHING rather than search, pass query='*' — that lists the product " +
-        "(honouring `entity` and `mode`) in a stable order instead of ranking it, which is " +
-        "what you want when the task is 'what can this product do' rather than a lookup. " +
-        "TO PAGE, send `offset`: every response carries `offset` and, when more matched, " +
-        "`next_offset` — resend the SAME query with that value. `next_offset` is absent on " +
-        "the last page, so walk until it stops rather than comparing counts.", {
+    tools.searchCapability = server.tool("searchCapability", "Find capabilities in ONE product by plain language. CALL listProducts FIRST; `product` must be spelled exactly as listProducts spells it. If `weak_match` is true, search again with `suggested_vocabulary` before invoking. Results are a shortlist: call describeCapability for the contract, then invokeCapability. query='*' lists all; page with `next_offset`.", {
         query: z
             .string()
-            .describe("What you are trying to do, in plain language. Pass '*' (or 'all') to BROWSE " +
-            "instead of search: every capability in the product, in a stable order, " +
-            "paginated — use it when you want to see the surface rather than find one thing."),
+            .describe("Goal in plain language, or '*' to list every capability."),
         entity: z
             .string()
             .optional()
@@ -430,9 +387,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // refused here instead, by a message that names listProducts.
         product: z
             .string()
-            .describe("Which product to search, named exactly as listProducts spells it. Call " +
-            "listProducts with the user's request to get the name — and to find out " +
-            "whether the products clash over it, in which case ask the user first."),
+            .describe("Product name, exactly as listProducts spells it."),
         // `product_choice` USED TO LIVE HERE, AND WAS ITS OWN DEFEAT.
         //
         // A required enum of 'user_confirmed' | 'not_asked' publishes, in the schema every
@@ -445,18 +400,11 @@ export function addCapabilityRegistryTools(server, deps, config) {
         routing_token: z
             .string()
             .optional()
-            .describe("The `routing_token` from the last listProducts call or product_ambiguous " +
-            "refusal — it carries what that step concluded about the user's request, " +
-            "signed. Always pass the most recent one. When it reports a clash, send the " +
-            "user's answer in `user_words` alongside it; neither works alone."),
+            .describe("Latest `routing_token` from listProducts or a clash refusal; send with `user_words` after a clash."),
         user_words: z
             .string()
             .optional()
-            .describe("The USER'S OWN words, verbatim, that settle which product this is — either " +
-            "the product's name or a term only one product uses ('quality gate', 'test " +
-            "plan'). Quote them; do not paraphrase, and do not write words the user did " +
-            "not say. When a query could mean either product this is what lifts the " +
-            "refusal, because it is checked against the index rather than taken on trust."),
+            .describe("The user's own words, verbatim, naming the product or a term only it uses. Never paraphrase."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -465,8 +413,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         offset: z
             .number()
             .optional()
-            .describe("Skip this many results — send the `next_offset` from the previous response " +
-            "with the SAME query to get the next page. Omit for the first page."),
+            .describe("`next_offset` from the previous page, with the same query."),
     }, {
         title: "Search Capabilities",
         readOnlyHint: true,
@@ -723,16 +670,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 : {}),
         });
     });
-    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.", {
+    tools.describeCapability = server.tool("describeCapability", "Full contract (parameters, returns, response shapes) for ONE capability from searchCapability. Call it before invokeCapability. Identify by `name`; use `method` + `path` only when no name was returned.", {
         name: z
             .string()
             .optional()
@@ -747,14 +685,11 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .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."),
+            .describe("Owning product; needed only when names or paths collide."),
         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'."),
+            .describe("'success' (default), 'all' (adds error shapes, larger) or 'none'."),
     }, {
         title: "Describe Capability",
         readOnlyHint: true,
@@ -817,17 +752,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
             return refuse("describeCapability", "unexpected_error", "that capability could not be described", undefined, identity);
         }
     });
-    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 " +
-        "makes exactly one request and returns the product's own response untouched; when " +
-        "`completed` is false there is another page, which you fetch by sending the " +
-        "capability's own page parameter. If the mode is 'write' you MUST ask the user " +
-        "first, then resend with user_permission='granted' and a change_summary; both are " +
-        "recorded. Capabilities whose mode is 'destructive' (deletes) are refused outright — " +
-        "archiving, closing and merging are ordinary writes and DO run, so read the mode and " +
-        "intent before confirming with the user.", {
+    tools.invokeCapability = server.tool("invokeCapability", "Run a capability after describeCapability, by `name` (or `method` + `path` if unnamed); args go in path_params / query / body. If `completed` is false, fetch the next page. Writes: ask the user first, then resend with user_permission='granted' and a change_summary. Deletes are refused; archive, close and merge are writes.", {
         name: z
             .string()
             .optional()
@@ -855,8 +780,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .describe("Body fields, under the spec's names."),
         product: productArg()
             .optional()
-            .describe(`Which product owns the capability (${productList}). searchCapability returns it ` +
-            "on every result; required only when two products share a name or a path."),
+            .describe("Owning product; needed only when names or paths collide."),
         user_permission: z
             .enum(PERMISSION_VALUES)
             .optional()

package/dist/tools/get-failure-logs.js

@@ -115,7 +115,7 @@ export async function getFailureLogs(args, config) {
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
     const tools = {};
-    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs, or the session video URL, for an Automate/App Automate session." +
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs or the video URL for an Automate/App Automate session." +
         NEEDS_SESSION_ID, {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])

package/dist/tools/live.js

@@ -15,14 +15,14 @@ const LiveArgsShape = {
         .describe("Desktop OS ('Windows' or 'OS X') or mobile OS ('android','ios','winphone')"),
     desiredOSVersion: z
         .string()
-        .describe("The OS version must be specified as a version number (e.g., '10', '14.0') or as a keyword such as 'latest' or 'oldest'. Normalize variations like 'newest' or 'most recent' to 'latest', and terms like 'earliest' or 'first' to 'oldest'. For macOS, version names (e.g., 'Sequoia') must be used instead of numeric versions."),
+        .describe("Version number or 'latest'/'oldest'; macOS takes names, e.g. 'Sequoia'."),
     desiredBrowser: z
         .enum(["chrome", "firefox", "safari", "edge", "ie"])
         .describe("Browser for desktop (Chrome, IE, Firefox, Safari, Edge)"),
     desiredBrowserVersion: z
         .string()
         .optional()
-        .describe("Browser version for desktop (e.g. '133.2', 'latest'). If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'."),
+        .describe("Desktop browser version, or 'latest' / 'oldest'."),
     desiredDevice: z.string().optional().describe("Device name for mobile"),
 };
 const LiveArgsSchema = z.object(LiveArgsShape);

package/dist/tools/rca-agent-utils/constants.js

@@ -8,7 +8,7 @@ export const FETCH_RCA_PARAMS = {
     testId: z
         .array(z.number().int())
         .max(3)
-        .describe("Array of integer test IDs to fetch RCA data for (maximum 3 IDs). These must be numeric test IDs, not session IDs or strings. If not provided, use the listTestIds tool to get all failed testcases. If more than 3 IDs are provided, only the first 3 will be processed."),
+        .describe("Up to 3 numeric test ids from listTestIds (not session ids)."),
 };
 export const GET_BUILD_ID_PARAMS = {
     browserStackProjectName: z
@@ -21,7 +21,7 @@ export const GET_BUILD_ID_PARAMS = {
 export const LIST_TEST_IDS_PARAMS = {
     buildId: z
         .string()
-        .describe("The Browserstack Build ID of the test run. If not known, use the getBuildId tool to fetch it using project and build name"),
+        .describe("Build id; get it with getBuildId or listBuildId."),
     status: z
         .nativeEnum(TestStatus)
         .describe("Filter tests by status. If not provided, all tests are returned. Example for RCA usecase always use failed status"),

package/dist/tools/rca-agent.js

@@ -131,7 +131,7 @@ export async function listTestIdsTool(args, config) {
 }
 export default function addRCATools(server, config) {
     const tools = {};
-    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval." +
+    tools.fetchRCA = server.tool("fetchRCA", "AI root cause for failed Automate/App Automate tests. Suggests fixes only; never auto-apply, require explicit user approval." +
         NEEDS_TEST_IDS, FETCH_RCA_PARAMS, {
         title: "Fetch Root Cause Analysis",
         readOnlyHint: true,

package/dist/tools/sdk-utils/common/constants.d.ts

@@ -2,7 +2,7 @@ export declare const IMPORTANT_SETUP_WARNING: string;
 export declare const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export declare const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export declare const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
-export declare const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
+export declare const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run web tests on BrowserStack Automate with the SDK (functional or integration). For Percy visual testing use the Percy tool.";
 export declare const SIMULATE_PERCY_CHANGE_DESCRIPTION = "Integrate Percy visual testing into new projects and demonstrate visual change detection through a step-by-step simulation. This tool handles initial Percy integration, setup, and creates a working demonstration for new users. Primary tool for prompts like: \"Integrate percy for this project\", \"Integrate percy in this project {project_name}\"";
 export declare const PERCY_REPLACE_REGEX: RegExp;
 export declare const PERCY_SNAPSHOT_INSTRUCTION = "\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n";

package/dist/tools/sdk-utils/common/constants.js

@@ -3,7 +3,7 @@ export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the
 export const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
-export const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
+export const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run web tests on BrowserStack Automate with the SDK (functional or integration). For Percy visual testing use the Percy tool.";
 export const SIMULATE_PERCY_CHANGE_DESCRIPTION = `Integrate Percy visual testing into new projects and demonstrate visual change detection through a step-by-step simulation. This tool handles initial Percy integration, setup, and creates a working demonstration for new users. Primary tool for prompts like: "Integrate percy for this project", "Integrate percy in this project {project_name}"`;
 export const PERCY_REPLACE_REGEX = /Invoke listTestFiles\(\) with the provided directories[\s\S]*?- DO NOT STOP until you add commands in all the files or you reach end of the files\./;
 export const PERCY_SNAPSHOT_INSTRUCTION = `

package/dist/tools/sdk-utils/common/schema.js

@@ -63,7 +63,7 @@ export const RunTestsOnBrowserStackParamsShape = {
         .array(DeviceSchema)
         .max(3)
         .default([])
-        .describe("Device objects array. Use the object format directly - no transformation needed. Add only when user explicitly requests devices. Examples: [{ platform: 'windows', osVersion: '11', browser: 'chrome', browserVersion: 'latest' }] or [{ platform: 'android', deviceName: 'Samsung Galaxy S24', osVersion: '14', browser: 'chrome' }]."),
+        .describe("Only devices the user asked for, e.g. [{ platform: 'windows', osVersion: '11', browser: 'chrome', browserVersion: 'latest' }]."),
 };
 export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
 export const RunTestsOnBrowserStackSchema = z.object(RunTestsOnBrowserStackParamsShape);

package/dist/tools/selfheal.js

@@ -417,11 +417,7 @@ export async function prepareSelfHealingPlanTool(args, config) {
 // Registers the fetchSelfHealSelector tool with the MCP server
 export default function addSelfHealTools(server, config) {
     const tools = {};
-    tools.fetchSelfHealedSelectors = server.tool("fetchSelfHealedSelectors", "Fetch BrowserStack self-healed selectors plus the test source code for " +
-        "the run. Provide exactly one of `sessionId` (single Automate / " +
-        "App-Automate session) or `buildUuid` (full self-healing report for a " +
-        "build). Pass the returned locator pairs to `prepareSelfHealingPlan` " +
-        "to plan edits." +
+    tools.fetchSelfHealedSelectors = server.tool("fetchSelfHealedSelectors", "Fetch self-healed selectors and the test source. Pass exactly one of `sessionId` or `buildUuid`; give the pairs to prepareSelfHealingPlan." +
         NEEDS_SESSION_ID, {
         sessionId: z
             .string()
@@ -481,17 +477,7 @@ export default function addSelfHealTools(server, config) {
     // Flexible entry point for the `sessions` argument. See normalizers above
     // for the accepted alternate shapes.
     const sessionsFieldSchema = z.preprocess(normalizeSessionsInput, z.array(sessionPayloadSchema).min(1));
-    tools.prepareSelfHealingPlan = server.tool("prepareSelfHealingPlan", "Build a self-healing edit plan that bundles locator pairs with test " +
-        "source code for the calling LLM to apply with its own editing tools. " +
-        "This tool does NOT modify files — it returns structured context so " +
-        "the LLM can edit only the relevant call sites (avoids blind " +
-        "find/replace across shared ids/classes). `sessions` accepts the " +
-        "canonical shape `[{sessionId, locators: [{original, healed, " +
-        "thought?}]}]`, a single session object, an envelope `{sessions: " +
-        "[...]}`, the raw report `{healing_logs: [...]}` (with " +
-        "`healed_selectors` aliasing `locators`), and snake_case keys " +
-        "(`session_id`, `original_locator`, `healed_locator`, " +
-        "`healing_thought`)." +
+    tools.prepareSelfHealingPlan = server.tool("prepareSelfHealingPlan", "Build an edit plan from healed locator pairs plus test source; it does NOT modify files. `sessions`: [{sessionId, locators: [{original, healed}]}] or the raw healing report." +
         NEEDS_SESSION_ID, {
         sessions: sessionsFieldSchema.describe("Sessions to plan edits for. See tool description for accepted shapes."),
     }, {

package/dist/tools/testmanagement-utils/create-testcase.js

@@ -15,10 +15,10 @@ export const customFieldValueSchema = z.union([
 export const CreateTestCaseSchema = z.object({
     project_identifier: z
         .string()
-        .describe("The ID of the BrowserStack project where the test case should be created. If no project identifier is provided, ask the user if they would like to create a new project using the createProjectOrFolder tool."),
+        .describe("Project id (PR-*). If none, offer createProjectOrFolder."),
     folder_id: z
         .string()
-        .describe("The ID of the folder within the project where the test case should be created. If not provided, ask the user if they would like to create a new folder using the createProjectOrFolder tool."),
+        .describe("Folder id. If none, offer createProjectOrFolder."),
     name: z.string().describe("Name of the test case."),
     description: z
         .string()
@@ -66,7 +66,7 @@ export const CreateTestCaseSchema = z.object({
     priority: z
         .string()
         .optional()
-        .describe("Priority of the test case. Accepts either display name (e.g. 'Critical', 'High', 'Medium', 'Low') or internal name (e.g. 'medium'). If omitted, the project default (usually 'Medium') is applied. Valid values are per-project and discoverable via the form-fields endpoint."),
+        .describe("Priority, e.g. 'High' or 'medium'; values vary per project; default Medium."),
     case_type: z
         .string()
         .optional()

package/dist/tools/testmanagement-utils/list-testcases.js

@@ -13,7 +13,7 @@ export const ListTestCasesSchema = z.object({
     folder_id: z
         .string()
         .optional()
-        .describe("Optional. If provided, only return test cases in this folder. If omitted, returns all test cases in the project. Folder ids can be discovered via listFolders."),
+        .describe("Only this folder's cases (ids from listFolders). Omit for all."),
     case_type: z
         .string()
         .optional()

package/dist/tools/testmanagement-utils/update-testcase.js

@@ -37,15 +37,15 @@ export const UpdateTestCaseSchema = z.object({
     priority: z
         .string()
         .optional()
-        .describe("Updated priority. Accepts either display name (e.g. 'Medium', 'Critical', 'High', 'Low') or internal name (e.g. 'medium'). Valid values are per-project and discoverable via the form-fields endpoint."),
+        .describe("Priority, e.g. 'High' or 'medium'; values vary per project."),
     case_type: z
         .string()
         .optional()
-        .describe("Updated test case type. Accepts either display name (e.g. 'Functional', 'Regression', 'Smoke & Sanity') or internal name (e.g. 'functional', 'smoke_sanity'). Valid values are per-project."),
+        .describe("Type, e.g. 'Functional' or 'smoke_sanity'; values vary per project."),
     automation_status: z
         .string()
         .optional()
-        .describe("Updated automation status. Use internal name such as 'not_automated', 'automated', 'automation_not_required', 'cannot_be_automated', or 'obsolete'."),
+        .describe("e.g. not_automated, automated, automation_not_required, obsolete."),
     status: z
         .string()
         .optional()

package/dist/tools/testmanagement.js

@@ -441,15 +441,14 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management." +
-        NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
+    tools.createTestCase = server.tool("createTestCase", "Create a test case in BrowserStack Test Management." + NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
         title: "Create Test Case",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestCaseTool(args, config, server));
-    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified." +
+    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case; only the supplied fields change." +
         NEEDS_PROJECT_ID, UpdateTestCaseSchema.shape, {
         title: "Update Test Case",
         readOnlyHint: false,
@@ -457,7 +456,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestCaseTool(args, config, server));
-    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination." +
+    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally one folder (see listFolders). Filters: case_type, priority, paging." +
         NEEDS_PROJECT_ID, ListTestCasesSchema.shape, {
         title: "List Test Cases",
         readOnlyHint: true,
@@ -465,7 +464,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestCasesTool(args, config, server));
-    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders." +
+    tools.listFolders = server.tool("listFolders", "List folders (id, name, counts) in a project; parent_id lists sub-folders." +
         NEEDS_PROJECT_ID, ListFoldersSchema.shape, {
         title: "List Folders",
         readOnlyHint: true,
@@ -487,24 +486,21 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestRunTool(args, config, server));
-    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)" +
-        NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs with filters (dates, assignee, state)." + NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
         title: "List Test Runs",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestRunsTool(args, config, server));
-    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it." +
-        NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run or add test cases to it." + NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
         title: "Update Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestRunTool(args, config, server));
-    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API." +
-        NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a test run." + NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
         title: "Add Test Result",
         readOnlyHint: false,
         openWorldHint: false,
@@ -526,7 +522,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createTestCasesFromFileTool(args, context, config, server));
-    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent." +
+    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case." +
         NEEDS_PROJECT_ID, CreateLCAStepsSchema.shape, {
         title: "Create LCA Steps",
         readOnlyHint: false,
@@ -534,7 +530,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createLCAStepsTool(args, context, config, server));
-    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination." +
+    tools.listTestPlans = server.tool("listTestPlans", "List test plans (TP-*) with status, dates and run counts; paginated." +
         NEEDS_PROJECT_ID +
         PLAN_WRITES_VIA_CAPABILITIES, ListTestPlansSchema.shape, {
         title: "List Test Plans",
@@ -543,7 +539,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestPlansTool(args, config, server));
-    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports." +
+    tools.getTestPlan = server.tool("getTestPlan", "Get a test plan (TP-*): metadata, linked runs, case count and status summary." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
         PLAN_WRITES_VIA_CAPABILITIES, GetTestPlanSchema.shape, {
@@ -553,7 +549,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => getTestPlanTool(args, config, server));
-    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination." +
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-plans under a test plan (TP-*); paginated." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
         PLAN_WRITES_VIA_CAPABILITIES, ListSubTestPlansSchema.shape, {
@@ -563,7 +559,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listSubTestPlansTool(args, config, server));
-    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs." +
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Get a sub-plan (STP-*): metadata and linked runs." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
         PLAN_WRITES_VIA_CAPABILITIES, GetSubTestPlanSchema.shape, {

package/dist/tools/tool-handoff.d.ts

@@ -23,7 +23,7 @@
  * twenty hand-written variants drift into twenty different signals.
  */
 /** No tool lists projects, so this genuinely has to go to the agent. */
-export declare const NEEDS_PROJECT_ID: string;
+export declare const NEEDS_PROJECT_ID = " Needs a project id (PR-*); if you lack one, get it from the capability functions.";
 /** A sibling tool can produce the id — prefer it over the agent. */
 export declare function needsIdFrom(idLabel: string, sourceTool: string): string;
 /**
@@ -60,7 +60,7 @@ export declare const NEEDS_BUILD_ID: string;
  * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
  * pointing at the agent when a real tool exists is exactly what the header above forbids.
  */
-export declare const NEEDS_SESSION_ID: string;
+export declare const NEEDS_SESSION_ID = " Needs a session id: listSessions lists them; getBuildId or listBuildId finds the build.";
 /** A completed scan's ids come from startAccessibilityScan, or from the agent. */
 export declare const NEEDS_A11Y_SCAN_ID: string;
 /** Auth-config ids are not listable by any tool here. */

package/dist/tools/tool-handoff.js

@@ -23,9 +23,7 @@
  * twenty hand-written variants drift into twenty different signals.
  */
 /** No tool lists projects, so this genuinely has to go to the agent. */
-export const NEEDS_PROJECT_ID = " Requires a project identifier (PR-*). No tool here lists projects, so if you do not " +
-    "have one, use the capability functions to list the Test Management projects, then " +
-    "retry this tool with the identifier they return.";
+export const NEEDS_PROJECT_ID = " Needs a project id (PR-*); if you lack one, get it from the capability functions.";
 /** A sibling tool can produce the id — prefer it over the agent. */
 export function needsIdFrom(idLabel, sourceTool) {
     return ` Requires ${idLabel}. Call ${sourceTool} first if you do not have it.`;
@@ -36,9 +34,8 @@ export function needsIdFrom(idLabel, sourceTool) {
  * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
  * "create me a project" through the agent before letting the tool run.
  */
-export const PROJECT_ID_ONLY_FOR_FOLDER = " Creating a project needs no identifier. Creating a folder inside an EXISTING project " +
-    "needs that project's identifier (PR-*); no tool here lists projects, so use the " +
-    "capability functions to look it up.";
+export const PROJECT_ID_ONLY_FOR_FOLDER = " Creating a project needs no identifier; a folder inside an EXISTING project needs " +
+    "its id (PR-*), from the capability functions.";
 /** A test plan id (TP-*) comes from listTestPlans. */
 export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
 /**
@@ -58,9 +55,8 @@ export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "
  * completes on a client that can show a prompt. On one that cannot, the intended write is
  * refused rather than performed.
  */
-export const PLAN_WRITES_VIA_CAPABILITIES = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
-    "available as tools here: use the capability functions, which reach Test Management's " +
-    "own API for these operations. They ask you to confirm before changing anything.";
+export const PLAN_WRITES_VIA_CAPABILITIES = " Creating a test plan or sub-plan, and linking or unlinking test runs, are not " +
+    "available as tools here: use the capability functions (they ask you to confirm first).";
 /** A build id comes from either build-lookup tool. */
 export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
 /**
@@ -68,14 +64,12 @@ export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId
  * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
  * pointing at the agent when a real tool exists is exactly what the header above forbids.
  */
-export const NEEDS_SESSION_ID = " Requires a session id. listSessions lists them for a build; if you do not have the " +
-    "build either, getBuildId or listBuildId resolves one from a project and build name.";
+export const NEEDS_SESSION_ID = " Needs a session id: listSessions lists them; getBuildId or listBuildId finds the build.";
 /** A completed scan's ids come from startAccessibilityScan, or from the agent. */
-export const NEEDS_A11Y_SCAN_ID = " Requires the ids of a completed scan, which are returned by startAccessibilityScan. " +
-    "No tool here lists past scans, so if you do not have the ids, start a new scan rather " +
-    "than guessing.";
+export const NEEDS_A11Y_SCAN_ID = " Needs a completed scan's ids from startAccessibilityScan; past scans are not " +
+    "listed, so start a new scan rather than guessing.";
 /** Auth-config ids are not listable by any tool here. */
-export const NEEDS_A11Y_CONFIG_ID = " Requires the numeric id returned by createAccessibilityAuthConfig. No tool here lists " +
-    "existing configurations, so if you do not have the id, create one rather than guessing.";
+export const NEEDS_A11Y_CONFIG_ID = " Needs the id from createAccessibilityAuthConfig; configs are not listed, so create " +
+    "one rather than guessing.";
 /** Test ids come from listTestIds, which itself needs a build id. */
 export const NEEDS_TEST_IDS = needsIdFrom("test ids", "listTestIds");

package/package.json

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