@browserstack/mcp-server 1.5.0-beta.9 → 1.5.1-beta.1

package/dist/tools/selfheal.js

@@ -3,6 +3,7 @@ import { getSelfHealSelectors, fetchSelfHealingReportByBuild, } from "./selfheal
 import { fetchTestCodeForSessions, formatTestCodeAsContext, describeTestCodeFetchIssues, } from "./selfheal-utils/fetch-test-code.js";
 import logger from "../logger.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import { NEEDS_SESSION_ID } from "./tool-handoff.js";
 // Local helper: returns the server-configured BrowserStack credentials, or
 // null when either is missing. Lives here because the self-heal tools need
 // to degrade gracefully — `getBrowserStackAuth` throws, which is wrong for
@@ -17,9 +18,10 @@ function resolveBrowserStackAuth(config) {
     return { config };
 }
 const CREDS_PROMPT_TEXT = "BrowserStack credentials are not configured on the MCP server. " +
-    "Ask the user to set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY " +
-    "in the server environment (https://www.browserstack.com/accounts/profile/details), " +
-    "restart the MCP server, and retry. Do NOT ask the user to paste credentials in chat.";
+    "Set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in the server " +
+    "environment (https://www.browserstack.com/accounts/profile/details), " +
+    "restart the MCP server, and retry. Credentials are read from the server " +
+    "environment, not from chat.";
 function credsMissingResult() {
     return {
         content: [{ type: "text", text: CREDS_PROMPT_TEXT }],
@@ -44,20 +46,13 @@ function trimOrUndefined(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-/**
- * Wraps per-status guidance in a HEAD-OF-RESPONSE banner the LLM is unlikely
- * to paraphrase away. The banner must come BEFORE the plan JSON so the model
- * anchors on it when composing its user-facing reply.
- */
+/** Per-status notes, placed ahead of the plan JSON. */
 function buildWarningBanner(body) {
     return [
-        "## ATTENTION — test code fetch did not return usable source",
+        "## Test code fetch did not return usable source",
         "",
-        "Read this block BEFORE composing your reply to the user. When relaying " +
-            "this to the user, quote the provided phrasings below as closely as " +
-            "possible — do NOT compress multiple statuses into a generic " +
-            "'credentials or session issue' message. If the status below is " +
-            "`non_sdk_build`, it is definitely NOT a credentials problem.",
+        "Each status below has a different cause and is reported separately; " +
+            "a `non_sdk_build` status is not a credentials problem.",
         "",
         body,
         "",
@@ -235,7 +230,7 @@ export async function fetchSelfHealSelectorTool(args, config) {
                         "Self-healing report fetched successfully (buildUuid mode). " +
                         "Work session-by-session: for each entry in `healing_logs[]`, " +
                         "pass `healed_selectors[]` to `prepareSelfHealingPlan` so the " +
-                        "calling LLM can apply the edits with its own file-editing " +
+                        "caller can apply the edits with its own file-editing " +
                         "tools (this server never writes files).\n" +
                         JSON.stringify(report, null, 2) +
                         (testCodeContext
@@ -262,9 +257,9 @@ export async function fetchSelfHealSelectorTool(args, config) {
 const PLAN_INSTRUCTIONS = [
     "## How to use this plan",
     "",
-    "This tool does NOT modify any files. It returns the healed-locator plan",
-    "and per-session test source code so that YOU (the calling LLM) can make",
-    "surgical edits with your own file-editing tools.",
+    "This tool does not modify any files. It returns the healed-locator plan",
+    "and per-session test source code so the caller can make targeted edits",
+    "with its own file-editing tools.",
     "",
     "For each session in the plan:",
     "  1. Read each `tests[].code` to understand the test intent — especially",
@@ -272,10 +267,10 @@ const PLAN_INSTRUCTIONS = [
     "  2. Locate the exact call site(s) in the user's local project that",
     "     correspond to the original locator. Use `tests[].filename` as the",
     "     first place to look.",
-    "  3. Edit ONLY the call sites that belong to this session's failing step.",
-    "     A single id / class value may appear in many places; do NOT blindly",
-    "     find/replace across the repo (e.g. two different elements both using",
-    '     id="foo" must be resolved individually).',
+    "  3. Edit only the call sites that belong to this session's failing step.",
+    "     A single id / class value may appear in many places, so a blanket",
+    "     find/replace across the repo is unsafe (e.g. two different elements",
+    '     both using id="foo" must be resolved individually).',
     "  4. The healing report speaks in CSS/xpath, but the source often uses",
     "     `By.id(...)`, `By.name(...)`, `By.css(...)` wrappers. Translate as",
     "     needed — e.g. `*[id=\"email-field\"]` → `By.id('email-field')`, or",
@@ -284,7 +279,7 @@ const PLAN_INSTRUCTIONS = [
     "",
     "If `tests[]` is empty for a session, the BrowserStack API did not return",
     "test code (credentials missing, or the session has no associated test",
-    "runs). Ask the user to point you at the right file before editing.",
+    "runs). The local file path is needed before editing.",
 ].join("\n");
 export async function prepareSelfHealingPlanTool(args, config) {
     const rawArgs = args;
@@ -388,7 +383,7 @@ export async function prepareSelfHealingPlanTool(args, config) {
         }
         catch (error) {
             logger.warn("Failed to fetch test code during plan preparation", error);
-            warningBanner = buildWarningBanner(`### Transport error while fetching test code\n\nDiagnosis: ${error instanceof Error ? error.message : String(error)}. This is not an auth issue.\n\nSay this to the user: "I hit a transport error fetching test code from BrowserStack. Want me to retry, or would you rather share the local test file directly so I can apply the healed locators?"`);
+            warningBanner = buildWarningBanner(`### Transport error while fetching test code\n\nDiagnosis: ${error instanceof Error ? error.message : String(error)}. This is not an auth issue.\n\nNext step: retry the fetch, or apply the healed locators to the local test file if the user shares its path.`);
         }
     }
     else if (!resolved && sessionIds.length > 0) {
@@ -399,14 +394,10 @@ export async function prepareSelfHealingPlanTool(args, config) {
                 "configured on the MCP server, so test code could not be fetched. " +
                 "The plan was still generated from the locator pairs you sent.",
             "",
-            "Say this to the user: \"I couldn't pull the test source " +
-                "automatically because BrowserStack credentials aren't configured " +
-                "on the MCP server. Please set BROWSERSTACK_USERNAME and " +
-                "BROWSERSTACK_ACCESS_KEY in the server environment and restart " +
-                "the MCP server, or point me at the local test file directly so " +
-                'I can apply the healed locators."',
-            "",
-            "Do NOT ask the user to paste credentials in chat.",
+            "Next step: set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in " +
+                "the server environment and restart the MCP server, or apply the " +
+                "healed locators to the local test file if the user shares its path. " +
+                "Credentials are read from the server environment, not from chat.",
         ].join("\n"));
     }
     const skippedNote = skipped.length > 0
@@ -430,7 +421,8 @@ export default function addSelfHealTools(server, config) {
         "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.", {
+        "to plan edits." +
+        NEEDS_SESSION_ID, {
         sessionId: z
             .string()
             .describe("Session ID. Mutually exclusive with buildUuid.")
@@ -499,11 +491,12 @@ export default function addSelfHealTools(server, config) {
         "[...]}`, the raw report `{healing_logs: [...]}` (with " +
         "`healed_selectors` aliasing `locators`), and snake_case keys " +
         "(`session_id`, `original_locator`, `healed_locator`, " +
-        "`healing_thought`).", {
+        "`healing_thought`)." +
+        NEEDS_SESSION_ID, {
         sessions: sessionsFieldSchema.describe("Sessions to plan edits for. See tool description for accepted shapes."),
     }, {
         title: "Prepare Self-Healing Plan",
-        readOnlyHint: true,
+        readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,

package/dist/tools/testmanagement-utils/TCG-utils/api.js

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../lib/apiClient.js";
-import { TCG_TRIGGER_URL, TCG_POLL_URL, FETCH_DETAILS_URL, FORM_FIELDS_URL, BULK_CREATE_URL, TC_DETAILS_MAX_BATCH, } from "./config.js";
+import { TCG_TRIGGER_URL, TCG_POLL_URL, FETCH_DETAILS_URL, FORM_FIELDS_URL, BULK_CREATE_URL, TC_DETAILS_MAX_BATCH, TCG_POLL_INTERVAL_MS, TCG_POLL_MAX_WAIT_MS, } from "./config.js";
 import { createTestCasePayload } from "./helpers.js";
 import { getBrowserStackAuth } from "../../../lib/get-auth.js";
 import { getTMBaseURL } from "../../../lib/tm-base-url.js";
@@ -118,9 +118,15 @@ export async function pollTestCaseDetails(traceRequestId, config) {
     let done = false;
     const tmBaseUrl = await getTMBaseURL(config);
     const TCG_POLL_URL_VALUE = TCG_POLL_URL(tmBaseUrl);
+    const deadline = Date.now() + TCG_POLL_MAX_WAIT_MS;
     while (!done) {
+        // Bail out if the backend never sends a "termination" message, so a stuck
+        // job cannot keep this loop (and its callers) alive forever.
+        if (Date.now() > deadline) {
+            throw new Error(`TCG test-case detail polling timed out after ${TCG_POLL_MAX_WAIT_MS}ms (trace ${traceRequestId})`);
+        }
         // add a bit of jitter to avoid synchronized polling storms
-        await new Promise((r) => setTimeout(r, 10000 + Math.random() * 5000));
+        await new Promise((r) => setTimeout(r, TCG_POLL_INTERVAL_MS + Math.random() * 5000));
         const poll = await apiClient.post({
             url: `${TCG_POLL_URL_VALUE}?x-bstack-traceRequestId=${encodeURIComponent(traceRequestId)}`,
             headers: {
@@ -159,7 +165,20 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
     const TCG_POLL_URL_VALUE = TCG_POLL_URL(tmBaseUrl);
     // Promisify interval-style polling using a wrapper
     await new Promise((resolve, reject) => {
-        const intervalId = setInterval(async () => {
+        const timers = {};
+        const stop = () => {
+            if (timers.interval)
+                clearInterval(timers.interval);
+            if (timers.timeout)
+                clearTimeout(timers.timeout);
+        };
+        // Hard wall-clock deadline: if the backend never sends a "termination"
+        // message, reject instead of letting the interval fire forever.
+        timers.timeout = setTimeout(() => {
+            stop();
+            reject(new Error(`TCG scenario polling timed out after ${TCG_POLL_MAX_WAIT_MS}ms (trace ${traceId})`));
+        }, TCG_POLL_MAX_WAIT_MS);
+        timers.interval = setInterval(async () => {
             try {
                 const poll = await apiClient.post({
                     url: `${TCG_POLL_URL_VALUE}?x-bstack-traceRequestId=${encodeURIComponent(traceId)}`,
@@ -169,7 +188,7 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
                     body: {},
                 });
                 if (poll.status !== 200) {
-                    clearInterval(intervalId);
+                    stop();
                     reject(new Error(`Polling error: ${poll.statusText || poll.status}`));
                     return;
                 }
@@ -221,16 +240,16 @@ export async function pollScenariosTestDetails(args, traceId, context, documentI
                         }
                     }
                     if (msg.type === "termination") {
-                        clearInterval(intervalId);
+                        stop();
                         resolve();
                     }
                 }
             }
             catch (err) {
-                clearInterval(intervalId);
+                stop();
                 reject(err);
             }
-        }, 10000); // 10 second interval
+        }, TCG_POLL_INTERVAL_MS);
     });
     // once all detail fetches are triggered, wait for them to complete
     const detailsList = await Promise.all(detailPromises);

package/dist/tools/testmanagement-utils/TCG-utils/config.d.ts

@@ -1,4 +1,6 @@
 export declare const TC_DETAILS_MAX_BATCH = 10;
+export declare const TCG_POLL_INTERVAL_MS = 10000;
+export declare const TCG_POLL_MAX_WAIT_MS: number;
 export declare const TCG_TRIGGER_URL: (baseUrl: string) => string;
 export declare const TCG_POLL_URL: (baseUrl: string) => string;
 export declare const FETCH_DETAILS_URL: (baseUrl: string) => string;

package/dist/tools/testmanagement-utils/TCG-utils/config.js

@@ -1,4 +1,9 @@
 export const TC_DETAILS_MAX_BATCH = 10;
+// Wall-clock bounds for the TCG generation polling loops. Without a hard
+// deadline, a job that never emits a "termination" message keeps the loop
+// (and every caller awaiting it) alive forever.
+export const TCG_POLL_INTERVAL_MS = 10_000;
+export const TCG_POLL_MAX_WAIT_MS = 10 * 60 * 1000; // 10 minutes
 export const TCG_TRIGGER_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/suggest-test-cases`;
 export const TCG_POLL_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/test-cases-polling`;
 export const FETCH_DETAILS_URL = (baseUrl) => `${baseUrl}/api/v1/integration/tcg/test-generation/fetch-test-case-details`;

package/dist/tools/testmanagement-utils/get-sub-testplan.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 /**
  * Schema for fetching a single sub-test-plan by identifier under a parent test
  * plan, including its linked test runs.
@@ -106,7 +107,9 @@ export async function getSubTestPlan(args, config) {
             `Sub-Test-Plan ${plan.identifier}: ${plan.name}`,
             `Parent plan: ${plan.parent_plan_id}`,
             `Status: ${plan.active_state}`,
-            plan.description ? `Description: ${plan.description}` : null,
+            plan.description
+                ? `Description:\n${wrapUntrusted("sub-test-plan description", plan.description)}`
+                : null,
             tagsLine,
             issuesLine,
             plan.start_date || plan.end_date
@@ -133,12 +136,12 @@ export async function getSubTestPlan(args, config) {
                 { type: "text", text: header + runsBlock },
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: wrapUntrusted("sub-test-plan (structured data)", JSON.stringify({
                         sub_test_plan: plan,
                         linked_test_runs: runs,
                         status_summary: statusSummary,
                         total_test_cases: totalCases,
-                    }, null, 2),
+                    }, null, 2)),
                 },
             ],
         };

package/dist/tools/testmanagement-utils/get-testplan.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 /**
  * Schema for fetching a single test plan by identifier, including its linked test runs.
  */
@@ -58,7 +59,9 @@ export async function getTestPlan(args, config) {
         const header = [
             `Test Plan ${plan.identifier}: ${plan.name}`,
             `Status: ${plan.active_state}`,
-            plan.description ? `Description: ${plan.description}` : null,
+            plan.description
+                ? `Description:\n${wrapUntrusted("test plan description", plan.description)}`
+                : null,
             plan.start_date || plan.end_date
                 ? `Dates: ${plan.start_date ?? "—"} → ${plan.end_date ?? "—"}`
                 : null,
@@ -83,12 +86,12 @@ export async function getTestPlan(args, config) {
                 { type: "text", text: header + runsBlock },
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: wrapUntrusted("test plan (structured data)", JSON.stringify({
                         test_plan: plan,
                         linked_test_runs: runs,
                         status_summary: statusSummary,
                         total_test_cases: totalCases,
-                    }, null, 2),
+                    }, null, 2)),
                 },
             ],
         };

package/dist/tools/testmanagement-utils/testcase-from-file.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 import { fetchFormFields, triggerTestCaseGeneration, pollScenariosTestDetails, bulkCreateTestCases, } from "./TCG-utils/api.js";
 import { buildDefaultFieldMaps, findBooleanFieldId, } from "./TCG-utils/helpers.js";
 import { signedUrlMap } from "../../lib/inmemory-store.js";
@@ -37,7 +38,7 @@ export async function createTestCasesFromFile(args, context, config) {
         content: [
             {
                 type: "text",
-                text: resultString,
+                text: wrapUntrusted("AI-generated test cases from the uploaded document", resultString),
             },
             {
                 type: "text",

package/dist/tools/testmanagement-utils/upload-file.js

@@ -19,16 +19,30 @@ export const UploadFileSchema = z.object({
         .describe("ID of the project where the file should be uploaded. Do not assume it, always ask user for it."),
     file_path: z
         .string()
-        .describe("Full path to the file that should be uploaded"),
+        .describe("Full path to the file that should be uploaded. Must be inside the " +
+        "directory configured via the MCP_UPLOAD_BASE_DIR environment variable."),
 });
 /**
  * Uploads a file to BrowserStack Test Management and returns the signed URL.
  */
 export async function uploadFile(args, config) {
     const { project_identifier, file_path } = args;
+    if (!appConfig.UPLOAD_BASE_DIR) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "File upload is disabled. Set the MCP_UPLOAD_BASE_DIR environment " +
+                        "variable to a directory that contains the files you want to upload, " +
+                        "then restart the MCP server. Uploads are restricted to that directory.",
+                },
+            ],
+            isError: true,
+        };
+    }
     try {
         // Canonicalize path and enforce upload safety rules (extension, size,
-        // hidden-directory traversal, optional base-dir containment).
+        // hidden-directory traversal, base-dir containment).
         const safePath = validateUploadPath(file_path, {
             allowedExtensions: TEST_MANAGEMENT_ATTACHMENT_EXTENSIONS,
             maxSizeBytes: MAX_ATTACHMENT_UPLOAD_BYTES,

package/dist/tools/testmanagement.js

@@ -19,6 +19,7 @@ import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-test
 import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
 import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
+import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_AGENT, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -263,11 +264,11 @@ export async function uploadProductRequirementFileTool(args, config, server) {
  */
 export async function createTestCasesFromFileTool(args, context, config, server) {
     try {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), undefined, config);
         return await createTestCasesFromFile(args, context, config);
     }
     catch (err) {
-        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err);
+        trackMCP("createTestCasesFromFile", server.server.getClientVersion(), err, config);
         return {
             content: [
                 {
@@ -432,35 +433,40 @@ export async function getSubTestPlanTool(args, config, server) {
  */
 export default function addTestManagementTools(server, config) {
     const tools = {};
-    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, {
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management." +
+        PROJECT_ID_ONLY_FOR_FOLDER, CreateProjFoldSchema.shape, {
         title: "Create Project or Folder",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", 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 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.", UpdateTestCaseSchema.shape, {
+    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,
         openWorldHint: false,
         destructiveHint: true,
         idempotentHint: true,
     }, (args) => updateTestCaseTool(args, config, server));
-    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination.", ListTestCasesSchema.shape, {
+    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,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestCasesTool(args, config, server));
-    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders.", ListFoldersSchema.shape, {
+    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,
         openWorldHint: false,
@@ -474,35 +480,39 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTemplatesTool(args, config, server));
-    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, {
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management." + NEEDS_PROJECT_ID, CreateTestRunSchema.shape, {
         title: "Create Test Run",
         readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => createTestRunTool(args, config, server));
-    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", 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's metadata and/or add test cases to it.", 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 specific test run via BrowserStack Test Management API.", 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,
         destructiveHint: false,
         idempotentHint: false,
     }, (args) => addTestResultTool(args, config, server));
-    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, {
+    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack." +
+        NEEDS_PROJECT_ID, UploadFileSchema.shape, {
         title: "Upload Product Requirement File",
         readOnlyHint: false,
         openWorldHint: false,
@@ -516,35 +526,47 @@ export default function addTestManagementTools(server, config) {
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createTestCasesFromFileTool(args, context, config, server));
-    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, {
+    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,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: false,
     }, (args, context) => createLCAStepsTool(args, context, config, server));
-    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination.", ListTestPlansSchema.shape, {
+    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_AGENT, ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listTestPlansTool(args, config, server));
-    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports.", GetTestPlanSchema.shape, {
+    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_AGENT, GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => getTestPlanTool(args, config, server));
-    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", ListSubTestPlansSchema.shape, {
+    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_AGENT, ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,
     }, (args) => listSubTestPlansTool(args, config, server));
-    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, {
+    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_AGENT, GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/tfa-rca-collaboration.js

@@ -83,7 +83,7 @@ export async function listTestsInFailureThemeTool(args, config) {
 }
 export default function addTfaRcaCollaborationTools(server, config) {
     const tools = {};
-    tools.tfaRcaTurn = server.tool(TOOL_NAME, "Submit one collaborative RCA turn for a test run to the TFA agent, then poll in-call for a result. Omit threadId on the first turn for a test run — this starts a new investigation thread; every following turn on that same test MUST pass back the threadId from the previous response, since a test run should have only one active thread at a time. Returns status RESOLVED (terminal, includes root_cause/related_prs), NEEDS_INFO (fulfill the asks and submit the next turn with the same threadId), or PENDING (still working — poll it with getTfaTurnResult using the returned turnId; do NOT call tfaRcaTurn again for the same turn, that submits a duplicate).", TFA_RCA_TURN_PARAMS, async (args, context) => {
+    tools.tfaRcaTurn = server.tool(TOOL_NAME, "Submit one collaborative RCA turn for a test run to the TFA agent, then poll in-call for a result. Omit threadId on the first turn for a test run — this starts a new investigation thread; every following turn on that same test passes back the threadId from the previous response, since a test run has only one active thread at a time. Returns status RESOLVED (terminal, includes root_cause/related_prs), NEEDS_INFO (fulfill the asks and submit the next turn with the same threadId), or PENDING (still working — poll it with getTfaTurnResult using the returned turnId; calling tfaRcaTurn again for the same turn submits a duplicate).", TFA_RCA_TURN_PARAMS, async (args, context) => {
         try {
             const result = await tfaRcaTurnTool(args, config, context);
             trackMCP(TOOL_NAME, server.server.getClientVersion(), undefined, config);

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

@@ -0,0 +1,66 @@
+/**
+ * Precondition sentences appended to a tool's description.
+ *
+ * WHY THESE EXIST. Nothing routes an MCP call: the client's model picks a tool from the
+ * descriptions alone. A tool that needs an identifier the caller does not have is a dead
+ * end — the model either asks the user for something they also do not know, or gives up.
+ * These sentences turn that dead end into a HANDOFF by naming, in the description itself,
+ * where the missing identifier comes from.
+ *
+ * Point at a sibling tool whenever one can produce the id — it is faster and more
+ * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
+ *
+ * The one that matters most: 15 of the 17 Test Management tools require a project
+ * identifier and NONE of them accepts its absence, yet no tool in this server lists
+ * projects. "List my projects" is the first step of nearly every Test Management journey
+ * and it was unserved, which is exactly why that request did not reach any tool unless a
+ * user named one explicitly.
+ *
+ * Keep these as shared constants, not per-tool prose: the wording is a routing signal, and
+ * twenty hand-written variants drift into twenty different signals.
+ */
+/** No tool lists projects, so this genuinely has to go to the agent. */
+export declare const NEEDS_PROJECT_ID: string;
+/** A sibling tool can produce the id — prefer it over the agent. */
+export declare function needsIdFrom(idLabel: string, sourceTool: string): string;
+/**
+ * createProjectOrFolder must NOT carry NEEDS_PROJECT_ID: `project_identifier` is optional
+ * there, and the create-a-PROJECT half needs no id at all. With the generic constant the
+ * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
+ * "create me a project" through the agent before letting the tool run.
+ */
+export declare const PROJECT_ID_ONLY_FOR_FOLDER: string;
+/** A test plan id (TP-*) comes from listTestPlans. */
+export declare const NEEDS_TEST_PLAN_ID: string;
+/**
+ * The ONLY capability handoff here: every other constant points at a tool that produces a
+ * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
+ * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
+ * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
+ * read tools, finds no create, and reports the capability as absent — which is exactly what
+ * a QA eval concluded.
+ *
+ * Deliberately narrow: it names the specific operations that are missing rather than
+ * inviting the model to route plan work to the agent generally, because the tool
+ * descriptions otherwise say to prefer a specific tool whenever one fits.
+ *
+ * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
+ * only completes on a client that can show a prompt. On one that cannot, the intended write
+ * comes back in `needs_approval` instead of happening.
+ */
+export declare const PLAN_WRITES_VIA_AGENT: string;
+/** A build id comes from either build-lookup tool. */
+export declare const NEEDS_BUILD_ID: string;
+/**
+ * Session ids ARE listable now — PR #395 added `listSessions`, which merged into main while
+ * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
+ * pointing at the agent when a real tool exists is exactly what the header above forbids.
+ */
+export declare const NEEDS_SESSION_ID: string;
+/** 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. */
+export declare const NEEDS_A11Y_CONFIG_ID: string;
+/** Test ids come from listTestIds, which itself needs a build id. */
+export declare const NEEDS_TEST_IDS: string;