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

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

@@ -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()

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.3.0-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",