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

package/dist/lib/error.d.ts

@@ -1,4 +1,14 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Returns the most specific human-readable text for an error raised by an
+ * API call, capped at 500 characters. For an AxiosError with a response body
+ * it prefers the body's `message`, `error` or `errors` field, serialising
+ * objects, and uses the whole body when none of those fields exist. An empty,
+ * whitespace-only or HTML-document body falls back to the error's own message.
+ * @param err - The error object to describe
+ * @param defaultText - The fallback error message
+ */
+export declare function errorText(err: unknown, defaultText: string): string;
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format

package/dist/lib/error.js

@@ -1,23 +1,75 @@
 import { AxiosError } from "axios";
+const MAX_ERROR_TEXT = 500;
+const BODY_FIELDS = ["message", "error", "errors"];
+function clip(text) {
+    return text.length > MAX_ERROR_TEXT ? text.slice(0, MAX_ERROR_TEXT) : text;
+}
+const HTML_DOCUMENT = /^\s*<(!doctype|html)\b/i;
+function stringify(value) {
+    if (typeof value === "string") {
+        return HTML_DOCUMENT.test(value) ? "" : value.trim();
+    }
+    if (value === undefined || value === null)
+        return "";
+    try {
+        const json = JSON.stringify(value);
+        return json === "{}" || json === "[]" ? "" : (json ?? "");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Text taken from an API error body: the first non-empty `message`, `error`
+ * or `errors` field when any of them is present, otherwise the whole body.
+ * Returns undefined when the body carries no usable text.
+ */
+function bodyText(data) {
+    if (typeof data !== "object" || data === null) {
+        const text = stringify(data);
+        return text ? clip(text) : undefined;
+    }
+    const record = data;
+    const named = BODY_FIELDS.filter((key) => key in record);
+    if (named.length > 0) {
+        for (const key of named) {
+            const text = stringify(record[key]);
+            if (text)
+                return clip(text);
+        }
+        return undefined;
+    }
+    const text = stringify(record);
+    return text ? clip(text) : undefined;
+}
+/**
+ * Returns the most specific human-readable text for an error raised by an
+ * API call, capped at 500 characters. For an AxiosError with a response body
+ * it prefers the body's `message`, `error` or `errors` field, serialising
+ * objects, and uses the whole body when none of those fields exist. An empty,
+ * whitespace-only or HTML-document body falls back to the error's own message.
+ * @param err - The error object to describe
+ * @param defaultText - The fallback error message
+ */
+export function errorText(err, defaultText) {
+    if (err instanceof AxiosError) {
+        const text = bodyText(err.response?.data);
+        if (text)
+            return text;
+        return clip(err.message || defaultText);
+    }
+    if (err instanceof Error)
+        return clip(err.message || defaultText);
+    return defaultText;
+}
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format
  * @param defaultText - The fallback error message
  */
 export function formatAxiosError(err, defaultText) {
-    let text = defaultText;
-    if (err instanceof AxiosError && err.response?.data) {
-        const message = err.response.data.message ||
-            err.response.data.error ||
-            err.message ||
-            defaultText;
-        text = message;
-    }
-    else if (err instanceof Error) {
-        text = err.message;
-    }
     return {
-        content: [{ type: "text", text }],
+        content: [{ type: "text", text: errorText(err, defaultText) }],
         isError: true,
     };
 }

package/dist/lib/utils.js

@@ -7,6 +7,9 @@ export function sanitizeUrlParam(param) {
     return param.replace(/[;&|`$(){}[\]<>]/g, "");
 }
 const ONE_MB = 1048576;
+// sharp's default (~268M px) lets one image decode to ~1 GB of RGBA; 25M px caps it near 100 MB.
+const MAX_INPUT_PIXELS = 25_000_000;
+const MAX_IMAGE_DIMENSION = 1920;
 let sharpConfigured = false;
 //Compresses a base64 image intelligently to keep it under 1 MB if needed.
 export async function maybeCompressBase64(base64) {
@@ -25,11 +28,19 @@ export async function maybeCompressBase64(base64) {
             sharp.concurrency(1);
             sharpConfigured = true;
         }
-        const compressedBuffer = await sharp(buffer).png({ quality }).toBuffer();
+        const image = globalConfig.REMOTE_MCP
+            ? sharp(buffer, { limitInputPixels: MAX_INPUT_PIXELS }).resize({
+                width: MAX_IMAGE_DIMENSION,
+                height: MAX_IMAGE_DIMENSION,
+                fit: "inside",
+                withoutEnlargement: true,
+            })
+            : sharp(buffer);
+        const compressedBuffer = await image.png({ quality }).toBuffer();
         return compressedBuffer.toString("base64");
     }
     catch (err) {
-        logger.warn("Image compression unavailable (sharp failed to load); returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
+        logger.warn("Image compression failed; returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
         return base64;
     }
 }

package/dist/tools/accessibility.js

@@ -305,7 +305,8 @@ export default function addAccessibilityTools(server, config) {
             return handleMCPError("createAccessibilityAuthConfig", server, config, error);
         }
     });
-    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Get an accessibility auth config by ID." + NEEDS_A11Y_CONFIG_ID, {
+    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Retrieve an existing authentication configuration by ID." +
+        NEEDS_A11Y_CONFIG_ID, {
         configId: z.number().describe("ID of the auth configuration to retrieve"),
     }, {
         title: "Get Accessibility Auth Config",
@@ -316,7 +317,7 @@ export default function addAccessibilityTools(server, config) {
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
-    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch a completed scan's accessibility issues; page with `cursor`." +
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results." +
         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 the App Automate SDK for Appium tests. For pre-built Espresso or XCUITest suites use runAppTestsOnBrowserStack.";
+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_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 the App Automate SDK for Appium tests. For pre-built Espresso or XCUITest suites use runAppTestsOnBrowserStack.";
+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_SCHEMA = {
     detectedFramework: z
         .nativeEnum(AppSDKSupportedFrameworkEnum)
         .describe("The mobile automation framework configured in the project. Example: 'appium'"),
     detectedTestingFramework: z
         .nativeEnum(AppSDKSupportedTestingFrameworkEnum)
-        .describe("Test framework in the project, e.g. testng, behave, pytest, robot."),
+        .describe("The testing framework used in the project. Be precise with framework selection Example: '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("Only devices the user asked for, e.g. [['android', 'Samsung Galaxy S24', '14']]."),
+        .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']]"),
     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 = "Run pre-built Espresso (Android) or XCUITest (iOS) suites on BrowserStack by upload. Not for Appium: use setupBrowserStackAppAutomateTests.";
+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 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 = `Run pre-built Espresso (Android) or XCUITest (iOS) suites on BrowserStack by upload. Not for Appium: use setupBrowserStackAppAutomateTests.`;
+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 MobileDeviceSchema = z.object({
     platform: z
         .enum(["android", "ios"])
@@ -13,15 +13,31 @@ export const MobileDeviceSchema = z.object({
 export const RUN_APP_AUTOMATE_SCHEMA = {
     appPath: z
         .string()
-        .describe("Built .apk/.ipa inside MCP_UPLOAD_BASE_DIR (gradle assembleDebug, or xcodebuild archive and export)."),
+        .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."),
     testSuitePath: z
         .string()
-        .describe("Built suite inside MCP_UPLOAD_BASE_DIR (gradle assembleAndroidTest, or zipped .xctestrun + Runner.app)."),
+        .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."),
     devices: z
         .array(MobileDeviceSchema)
         .max(3)
         .default([])
-        .describe("Only devices the user asked for, e.g. [['android', 'Samsung Galaxy S24', '14']]."),
+        .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']]"),
     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", "Take a screenshot of an app running on a BrowserStack device.", {
+    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.", {
         desiredPhone: z
             .string()
-            .describe("Exact device name, e.g. 'iPhone 15 Pro Max'. Ask the user."),
+            .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."),
         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("Local .apk/.ipa path inside MCP_UPLOAD_BASE_DIR."),
+            .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."),
     }, {
         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", "Open an app on a real mobile device in App Live for a manual check or crash debugging.", {
+    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.", {
         desiredPhone: z
             .string()
-            .describe("Exact device name, e.g. 'iPhone 15 Pro Max'. Ask the user; never assume."),
+            .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. "),
         desiredPlatformVersion: z
             .string()
-            .describe("Version number, or 'latest' / 'oldest'."),
+            .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'."),
         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("Local .apk/.ipa path inside MCP_UPLOAD_BASE_DIR. Ask the user; never assume."),
+            .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."),
     }, {
         title: "Run App Live Session",
         readOnlyHint: false,

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

@@ -53,12 +53,19 @@ 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. 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.";
+"(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.";
 /**
  * `isError` marks a call that FAILED, not one that was refused.
  *

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

@@ -1,6 +1,10 @@
 import { SessionType } from "../../lib/constants.js";
 import { BrowserStackConfig } from "../../lib/types.js";
-export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<{
+export declare const MAX_SCREENSHOT_BYTES: number | undefined;
+export declare function parseScreenshotUrls(text: string): string[];
+export type Screenshot = {
     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

@@ -3,6 +3,10 @@ import { SessionType } from "../../lib/constants.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
 import globalConfig from "../../config.js";
+import { MAX_LOG_BYTES } from "../failurelogs-utils/utils.js";
+export const MAX_SCREENSHOT_BYTES = globalConfig.REMOTE_MCP
+    ? 10 * 1024 * 1024
+    : undefined;
 async function extractScreenshotUrls(sessionId, sessionType, config) {
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
@@ -14,47 +18,112 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
             "Content-Type": "application/json",
             Authorization: `Basic ${auth}`,
         },
+        maxContentLength: MAX_LOG_BYTES,
         raise_error: false,
     });
+    if (response.status === 413) {
+        throw new Error("The logs for this session are too large (over 5 MB) to find screenshots here. Open the session in the BrowserStack dashboard to view them.");
+    }
     await assertOkResponse(response, "Session");
     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 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]);
+    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;
             }
         }
     }
-    return urls;
+    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";
 }
+// Returns null for a screenshot over MAX_SCREENSHOT_BYTES so the rest still load.
 async function fetchAndCompress(url) {
-    const response = await apiClient.get({ url, responseType: "arraybuffer" });
+    const response = await apiClient.get({
+        url,
+        responseType: "arraybuffer",
+        maxContentLength: MAX_SCREENSHOT_BYTES,
+        raise_error: false,
+    });
+    if (response.status === 413) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to download screenshot: ${response.status} ${response.statusText}`);
+    }
     // Axios returns response.data as a Buffer for binary data
-    const base64 = Buffer.from(response.data).toString("base64");
-    return { url, base64: await maybeCompressBase64(base64) };
+    const buffer = Buffer.from(response.data);
+    const base64 = await maybeCompressBase64(buffer.toString("base64"));
+    // Detect AFTER compression: sharp re-encodes anything over 1 MB to PNG, so
+    // reading the original bytes would label a large JPEG with the wrong type.
+    return {
+        url,
+        base64,
+        mimeType: detectImageMimeType(Buffer.from(base64, "base64")),
+    };
 }
 //Converts screenshot URLs to base64 encoded images
 async function convertUrlsToBase64(urls) {
+    let results;
     // Hosted pods are memory-constrained: process one image at a time. Local runs
     // keep the concurrent path.
     if (globalConfig.REMOTE_MCP) {
-        const screenshots = [];
+        results = [];
         for (const url of urls) {
-            screenshots.push(await fetchAndCompress(url));
+            results.push(await fetchAndCompress(url));
         }
-        return screenshots;
     }
-    return Promise.all(urls.map(fetchAndCompress));
+    else {
+        results = await Promise.all(urls.map(fetchAndCompress));
+    }
+    const screenshots = results.filter((s) => s !== null);
+    if (urls.length > 0 && screenshots.length === 0) {
+        throw new Error("The screenshots in this session are too large (over 10 MB each) to fetch here. Open the session in the BrowserStack dashboard to view them.");
+    }
+    return screenshots;
 }
 //Fetches and converts screenshot URLs to base64 encoded images
 export async function fetchAutomationScreenshots(sessionId, sessionType = SessionType.Automate, config) {

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

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

@@ -189,11 +189,24 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return failed(message, extra);
     };
-    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.", {
+    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.", {
         query: z
             .string()
             .optional()
-            .describe("The user's request, in their own words; enables clash detection."),
+            .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."),
     }, {
         title: "List Capability Products",
         readOnlyHint: true,
@@ -336,7 +349,9 @@ 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 an entity: identifiers, relations and product vocabulary. Read before filtering or writing; ids often need resolving first.", {
+    tools.describeEntity = server.tool("describeEntity", "Describe one entity: what it is, what identifies it, what it relates to, and the " +
+        "vocabulary the product uses for it. Read this before filtering or writing, because " +
+        "ids and field values usually have to be resolved first.", {
         product: productArg().describe(`Which product the entity belongs to: ${productList}.`),
         entity: z.string().describe("Entity name, as listProducts returns it."),
     }, {
@@ -356,10 +371,38 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return ok({ product, entity, ...doc });
     });
-    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`.", {
+    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.", {
         query: z
             .string()
-            .describe("Goal in plain language, or '*' to list every capability."),
+            .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."),
         entity: z
             .string()
             .optional()
@@ -387,7 +430,9 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // refused here instead, by a message that names listProducts.
         product: z
             .string()
-            .describe("Product name, exactly as listProducts spells it."),
+            .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."),
         // `product_choice` USED TO LIVE HERE, AND WAS ITS OWN DEFEAT.
         //
         // A required enum of 'user_confirmed' | 'not_asked' publishes, in the schema every
@@ -400,11 +445,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
         routing_token: z
             .string()
             .optional()
-            .describe("Latest `routing_token` from listProducts or a clash refusal; send with `user_words` after a clash."),
+            .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."),
         user_words: z
             .string()
             .optional()
-            .describe("The user's own words, verbatim, naming the product or a term only it uses. Never paraphrase."),
+            .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."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -413,7 +465,8 @@ export function addCapabilityRegistryTools(server, deps, config) {
         offset: z
             .number()
             .optional()
-            .describe("`next_offset` from the previous page, with the same query."),
+            .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."),
     }, {
         title: "Search Capabilities",
         readOnlyHint: true,
@@ -670,7 +723,16 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 : {}),
         });
     });
-    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.", {
+    tools.describeCapability = server.tool("describeCapability", "The full contract for ONE capability you picked from searchCapability: its " +
+        "parameters grouped into path_params / query / body under the spec's own names, " +
+        "what it returns, and its declared response shapes fully expanded. Call this after " +
+        "search and before invokeCapability — search deliberately omits all of it, because " +
+        "it is only needed for the one capability you actually call. " +
+        "Identify it by `name`, exactly as search returned it; only when a result carries " +
+        "no `name` (some products publish none yet) pass `method` and `path` instead. " +
+        "Every parameter lists its type, whether it is required, its allowed values where " +
+        "the set is closed, and any limits the product declares — obey those before calling " +
+        "rather than discovering them from a rejected request.", {
         name: z
             .string()
             .optional()
@@ -685,11 +747,14 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .describe("Path with {placeholders} intact — only for capabilities returned without a `name`."),
         product: productArg()
             .optional()
-            .describe("Owning product; needed only when names or paths collide."),
+            .describe(`Which product owns it (${productList}). searchCapability returns it on every ` +
+            "result; required only when two products share a name or a path."),
         include_responses: z
             .enum(["success", "all", "none"])
             .optional()
-            .describe("'success' (default), 'all' (adds error shapes, larger) or 'none'."),
+            .describe("Which declared responses to expand: 'success' (default, the 2xx shape), 'all' " +
+            "(adds the error shapes — several times larger, and near-identical across " +
+            "endpoints), or 'none'."),
     }, {
         title: "Describe Capability",
         readOnlyHint: true,
@@ -752,7 +817,17 @@ export function addCapabilityRegistryTools(server, deps, config) {
             return refuse("describeCapability", "unexpected_error", "that capability could not be described", undefined, identity);
         }
     });
-    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.", {
+    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.", {
         name: z
             .string()
             .optional()
@@ -780,7 +855,8 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .describe("Body fields, under the spec's names."),
         product: productArg()
             .optional()
-            .describe("Owning product; needed only when names or paths collide."),
+            .describe(`Which product owns the capability (${productList}). searchCapability returns it ` +
+            "on every result; required only when two products share a name or a path."),
         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 video URL for an Automate/App Automate session." +
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs, or the session 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("Version number or 'latest'/'oldest'; macOS takes names, e.g. 'Sequoia'."),
+        .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."),
     desiredBrowser: z
         .enum(["chrome", "firefox", "safari", "edge", "ie"])
         .describe("Browser for desktop (Chrome, IE, Firefox, Safari, Edge)"),
     desiredBrowserVersion: z
         .string()
         .optional()
-        .describe("Desktop browser version, or 'latest' / 'oldest'."),
+        .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'."),
     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("Up to 3 numeric test ids from listTestIds (not session ids)."),
+        .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."),
 };
 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("Build id; get it with getBuildId or listBuildId."),
+        .describe("The Browserstack Build ID of the test run. If not known, use the getBuildId tool to fetch it using project and build name"),
     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", "AI root cause for failed Automate/App Automate tests. Suggests fixes only; never auto-apply, require explicit user approval." +
+    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." +
         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 web tests on BrowserStack Automate with the SDK (functional or integration). For Percy visual testing use the Percy tool.";
+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 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 web tests on BrowserStack Automate with the SDK (functional or integration). For Percy visual testing use the Percy tool.";
+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 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("Only devices the user asked for, e.g. [{ platform: 'windows', osVersion: '11', browser: 'chrome', browserVersion: 'latest' }]."),
+        .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' }]."),
 };
 export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
 export const RunTestsOnBrowserStackSchema = z.object(RunTestsOnBrowserStackParamsShape);

package/dist/tools/selfheal.js

@@ -417,7 +417,11 @@ 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 self-healed selectors and the test source. Pass exactly one of `sessionId` or `buildUuid`; give the pairs to prepareSelfHealingPlan." +
+    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." +
         NEEDS_SESSION_ID, {
         sessionId: z
             .string()
@@ -477,7 +481,17 @@ 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 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." +
+    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`)." +
         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("Project id (PR-*). If none, offer createProjectOrFolder."),
+        .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."),
     folder_id: z
         .string()
-        .describe("Folder id. If none, offer createProjectOrFolder."),
+        .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."),
     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, e.g. 'High' or 'medium'; values vary per project; default Medium."),
+        .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."),
     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("Only this folder's cases (ids from listFolders). Omit for all."),
+        .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."),
     case_type: z
         .string()
         .optional()

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

@@ -1,6 +1,6 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { z } from "zod";
-import { formatAxiosError } from "../../lib/error.js";
+import { errorText } from "../../lib/error.js";
 import { fetchFormFields, normalizeDefaultFields as normalizeDefaultFieldsFromForm, projectIdentifierToId, } from "./TCG-utils/api.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
@@ -37,15 +37,15 @@ export const UpdateTestCaseSchema = z.object({
     priority: z
         .string()
         .optional()
-        .describe("Priority, e.g. 'High' or 'medium'; values vary per project."),
+        .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."),
     case_type: z
         .string()
         .optional()
-        .describe("Type, e.g. 'Functional' or 'smoke_sanity'; values vary per project."),
+        .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."),
     automation_status: z
         .string()
         .optional()
-        .describe("e.g. not_automated, automated, automation_not_required, obsolete."),
+        .describe("Updated automation status. Use internal name such as 'not_automated', 'automated', 'automation_not_required', 'cannot_be_automated', or 'obsolete'."),
     status: z
         .string()
         .optional()
@@ -218,12 +218,14 @@ Error details: ${JSON.stringify(err.response?.data || err.message)}`,
                 isError: true,
             };
         }
-        const errorMessage = formatAxiosError(err, "Failed to update test case");
+        const status = err.response?.status;
+        const detail = errorText(err, "unknown error");
+        const hint = status === 401 ? " Check the BrowserStack credentials in use." : "";
         return {
             content: [
                 {
                     type: "text",
-                    text: `Failed to update test case: ${errorMessage}. Please verify your credentials and try again.`,
+                    text: `Failed to update test case${status ? ` (HTTP ${status})` : ""}: ${detail}.${hint}`,
                 },
             ],
             isError: true,

package/dist/tools/testmanagement.js

@@ -441,14 +441,15 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Create a test case in BrowserStack Test Management." + NEEDS_PROJECT_ID, CreateTestCaseSchema.shape, {
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to 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; only the supplied fields change." +
+    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." +
         NEEDS_PROJECT_ID, UpdateTestCaseSchema.shape, {
         title: "Update Test Case",
         readOnlyHint: false,
@@ -456,7 +457,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 one folder (see listFolders). Filters: case_type, priority, paging." +
+    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." +
         NEEDS_PROJECT_ID, ListTestCasesSchema.shape, {
         title: "List Test Cases",
         readOnlyHint: true,
@@ -464,7 +465,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestCasesTool(args, config, server));
-    tools.listFolders = server.tool("listFolders", "List folders (id, name, counts) in a project; parent_id lists sub-folders." +
+    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." +
         NEEDS_PROJECT_ID, ListFoldersSchema.shape, {
         title: "List Folders",
         readOnlyHint: true,
@@ -486,21 +487,24 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestRunTool(args, config, server));
-    tools.listTestRuns = server.tool("listTestRuns", "List test runs with filters (dates, assignee, state)." + NEEDS_PROJECT_ID, ListTestRunsSchema.shape, {
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)" +
+        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 or add test cases to it." + NEEDS_PROJECT_ID, UpdateTestRunSchema.shape, {
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/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 test run." + NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API." +
+        NEEDS_PROJECT_ID, AddTestResultSchema.shape, {
         title: "Add Test Result",
         readOnlyHint: false,
         openWorldHint: false,
@@ -522,7 +526,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." +
+    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." +
         NEEDS_PROJECT_ID, CreateLCAStepsSchema.shape, {
         title: "Create LCA Steps",
         readOnlyHint: false,
@@ -530,7 +534,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 (TP-*) with status, dates and run counts; paginated." +
+    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." +
         NEEDS_PROJECT_ID +
         PLAN_WRITES_VIA_CAPABILITIES, ListTestPlansSchema.shape, {
         title: "List Test Plans",
@@ -539,7 +543,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestPlansTool(args, config, server));
-    tools.getTestPlan = server.tool("getTestPlan", "Get a test plan (TP-*): metadata, linked runs, case count and status summary." +
+    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." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
         PLAN_WRITES_VIA_CAPABILITIES, GetTestPlanSchema.shape, {
@@ -549,7 +553,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => getTestPlanTool(args, config, server));
-    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-plans under a test plan (TP-*); paginated." +
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination." +
         NEEDS_PROJECT_ID +
         NEEDS_TEST_PLAN_ID +
         PLAN_WRITES_VIA_CAPABILITIES, ListSubTestPlansSchema.shape, {
@@ -559,7 +563,7 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listSubTestPlansTool(args, config, server));
-    tools.getSubTestPlan = server.tool("getSubTestPlan", "Get a sub-plan (STP-*): metadata and linked runs." +
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test 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 = " Needs a project id (PR-*); if you lack one, get it from the capability functions.";
+export declare const NEEDS_PROJECT_ID: string;
 /** 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 = " Needs a session id: listSessions lists them; getBuildId or listBuildId finds the build.";
+export declare const NEEDS_SESSION_ID: string;
 /** 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,7 +23,9 @@
  * 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 = " Needs a project id (PR-*); if you lack one, get it from the capability functions.";
+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.";
 /** 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.`;
@@ -34,8 +36,9 @@ 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; a folder inside an EXISTING project needs " +
-    "its id (PR-*), from the capability functions.";
+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.";
 /** A test plan id (TP-*) comes from listTestPlans. */
 export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
 /**
@@ -55,8 +58,9 @@ 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, are not " +
-    "available as tools here: use the capability functions (they ask you to confirm first).";
+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.";
 /** A build id comes from either build-lookup tool. */
 export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
 /**
@@ -64,12 +68,14 @@ 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 = " Needs a session id: listSessions lists them; getBuildId or listBuildId finds the build.";
+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.";
 /** A completed scan's ids come from startAccessibilityScan, or from the agent. */
-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.";
+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.";
 /** Auth-config ids are not listable by any tool here. */
-export const NEEDS_A11Y_CONFIG_ID = " Needs the id from createAccessibilityAuthConfig; configs are not listed, so create " +
-    "one rather than guessing.";
+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.";
 /** 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.2",
+  "version": "2.2.3-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",