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

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/capability-registry/bind.js

@@ -7,6 +7,8 @@
  * one is meant, which is exactly why the Python side used to rename body fields `body_*`.
  * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
  */
+import appConfig from "../../config.js";
+import { APP_BINARY_EXTENSIONS, MAX_APP_UPLOAD_BYTES, validateUploadPath, } from "../../lib/upload-validator.js";
 import { InvocationError } from "./index-loader.js";
 /**
  * String formats worth ENFORCING, as opposed to merely publishing.
@@ -202,6 +204,34 @@ export function coerce(value, param) {
 }
 function coerceType(value, param, label = param.name) {
     const expected = param.type;
+    if (expected === "any") {
+        // PASSES THROUGH UNTOUCHED, which is the whole point of declaring it. A polymorphic
+        // parameter reached the string branch and arrived as text: WebDriver's frame id takes a
+        // number, an element reference or null, and `null` sent as "null" is refused as an
+        // invalid argument — a failure that reads like the caller chose the wrong frame.
+        return value;
+    }
+    if (expected === "file") {
+        // CHECKED HERE, not at egress: `bind` runs dry before the write-consent gate, so a path
+        // that does not exist — or a base directory nobody configured — is refused before the
+        // user is asked to approve an upload that was never going to happen.
+        //
+        // The rules are the ones the server already applies to every other upload, so the
+        // answer does not depend on which surface asked.
+        const given = String(value ?? "").trim();
+        if (!given)
+            throw new InvocationError(`'${label}' must be a path to a file`);
+        try {
+            return validateUploadPath(given, {
+                allowedExtensions: APP_BINARY_EXTENSIONS,
+                maxSizeBytes: MAX_APP_UPLOAD_BYTES,
+                allowedBaseDir: appConfig.UPLOAD_BASE_DIR,
+            });
+        }
+        catch (error) {
+            throw new InvocationError(error instanceof Error ? error.message : String(error));
+        }
+    }
     if (expected === "object" || expected === "array") {
         // An opaque body object is passed through as given: the spec does not describe its
         // fields, so validating or reshaping it would mean inventing a contract.
@@ -267,6 +297,32 @@ function coerceType(value, param, label = param.name) {
     if (untyped && (typeof value === "object" || typeof value === "boolean")) {
         return value;
     }
+    // A DECLARED STRING IS NOT A LICENCE TO STRINGIFY ANYTHING.
+    //
+    // The untyped case above was fixed because `String(value)` destroyed objects the spec had
+    // declined to describe. A DECLARED string was left stringifying whatever arrived, and it
+    // is the worse of the two: an object sent for `create_test_case_comment`'s `comment` was
+    // serialised to the literal text "[object Object]", the API accepted it, the write
+    // returned 200, and the agent reported success in good faith. tm exposes no comment
+    // delete, so that text is now permanently on the case.
+    //
+    // A 400 teaches the caller what it got wrong. A 200 that stores "[object Object]" teaches
+    // it nothing and cannot be undone, so refuse here rather than let it reach the wire.
+    //
+    // `null` passes through instead of becoming the five characters "null", which no API has
+    // ever wanted: several string parameters document null as the way to CLEAR a field —
+    // `test_plan_id` says "send null or '' to unlink" — and stringifying it silently sent a
+    // value where the caller meant to send an absence.
+    if (expected === "string") {
+        if (value === null || value === undefined)
+            return value;
+        if (typeof value === "object") {
+            throw new InvocationError(`'${label}' must be a string, and was ${Array.isArray(value) ? "a list" : "an object"}. ` +
+                `Serialising it would send the text ` +
+                `${JSON.stringify(Array.isArray(value) ? "[object Array]" : "[object Object]")} ` +
+                `rather than its contents, and the call would succeed with that stored.`);
+        }
+    }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));

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

@@ -21,31 +21,7 @@ import { Transport } from "./egress.js";
 export declare function selectedEnvironment(): string;
 /** True when this product's host is account-specific and must be discovered per call. */
 export declare function isRegionSharded(product: string, source?: HostSource): boolean;
-/**
- * Resolve a product's host.
- *
- * Atlas resolves: an explicit per-session override, then the host for the session's
- * environment (`harness.extra_environments[env][product]`), then the profile's own
- * `base_url`. The same rungs, in the same order, with one addition:
- *
- *   1. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>            explicit, environment-agnostic
- *   2. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>      this environment's host
- *   3. CAPABILITY_REGISTRY_BASE_URLS {product:{env:url}} the same, as one map
- *   4. account discovery — the index's `base_urls`, probed
- *   5. the single host declared in the index, `base_url`
- *   6. refuse, by name
- *
- * DISCOVERY OUTRANKS THE DECLARED HOST, which is where this departs from Atlas. A declared
- * host is one fixed origin, so for a region-sharded product it would send every account
- * outside the default region to the wrong host — a failure that only shows up on those
- * accounts, and so passes any test run from inside the default one. Discovery answers with
- * the region the account is actually on; `base_url` is the fallback for when the probe
- * cannot answer at all.
- *
- * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
- * that reads like the caller's problem, when it is our missing configuration.
- */
-export declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport): Promise<string>;
+export declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport, host?: string): Promise<string>;
 /**
  * Locate the artifact(s).
  *

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

@@ -86,10 +86,49 @@ function credentialsFrom(config) {
  * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
  * that reads like the caller's problem, when it is our missing configuration.
  */
-export async function resolveBaseUrl(product, config, source, transport) {
+/**
+ * The host a capability named, as opposed to the product's own.
+ *
+ * `_HOST_` is in the override variable deliberately. The environment-suffixed form is
+ * `CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>`, so a bare
+ * `CAPABILITY_REGISTRY_BASE_URL_APPAUTOMATE_HUB` would mean the hub host or the "hub"
+ * environment depending on which the reader had in mind — and whichever the code chose,
+ * the other reading sends a call to the wrong origin silently.
+ *
+ * A named environment refuses rather than falling back to the declared host, for the same
+ * reason the product-level resolver does: a preprod session must not reach production
+ * because nobody defined preprod's hub.
+ */
+function resolveNamedHost(product, key, host, source, environment) {
+    const trim = (url) => url.replace(/\/$/, "");
+    const suffix = `${key}_HOST_${host.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+    const override = process.env[`CAPABILITY_REGISTRY_BASE_URL_${suffix}`];
+    if (override)
+        return trim(override);
+    if (environment) {
+        throw new InvocationError(`environment '${environment}' has no '${host}' host for product '${product}'. Set ` +
+            `CAPABILITY_REGISTRY_BASE_URL_${suffix}.`);
+    }
+    const declared = source?.hosts?.[host];
+    if (declared)
+        return trim(declared);
+    const known = Object.keys(source?.hosts ?? {});
+    throw new InvocationError(`that capability is served from the '${host}' host, which product '${product}' does ` +
+        `not declare. ` +
+        (known.length
+            ? `Its index defines: ${known.join(", ")}.`
+            : `Its index defines no named hosts.`) +
+        ` Set CAPABILITY_REGISTRY_BASE_URL_${suffix} to override.`);
+}
+export async function resolveBaseUrl(product, config, source, transport, host) {
     const key = product.toUpperCase();
     const environment = selectedEnvironment();
     const trim = (url) => url.replace(/\/$/, "");
+    // A capability that names a host is asking for one fixed origin, so none of the rungs
+    // below apply: discovery answers with the product's own host, and the declared
+    // `base_url` cannot serve this capability's paths at all.
+    if (host)
+        return resolveNamedHost(product, key, host, source, environment);
     const explicit = process.env[`CAPABILITY_REGISTRY_BASE_URL_${key}`];
     if (explicit)
         return trim(explicit);

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

@@ -14,7 +14,7 @@
 import { Credentials, Transport } from "./egress.js";
 import { Capability, ProductIndex } from "./types.js";
 /** What the resolver needs from a product's index to find its host. */
-export type HostSource = Pick<ProductIndex, "base_url" | "base_urls" | "probe_path" | "auth"> & {
+export type HostSource = Pick<ProductIndex, "base_url" | "base_urls" | "hosts" | "probe_path" | "auth"> & {
     capabilities?: Capability[];
 };
 /** Exposed for tests; a long-lived process must not pin a stale region forever. */

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

@@ -135,7 +135,19 @@ async function readBody(response) {
         const size = response.headers.get("content-length");
         return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
     }
-    const raw = await response.text().catch(() => "");
+    // A FAILED READ IS NOT AN EMPTY BODY. `fetch` resolves as soon as the headers arrive, so
+    // the abort timer can fire while the body is still streaming. Swallowing that here
+    // returned the status line with no payload — a slow session create came back as a 200
+    // carrying null, which reads as a successful start that forgot to mention the session id.
+    // The device was really allocated, so the caller then had a session it could not name and
+    // could not release. Re-throwing lets the transport report the call as failed.
+    let raw;
+    try {
+        raw = await response.text();
+    }
+    catch (error) {
+        throw new Error(`the response body could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
     if (!raw.trim())
         return null;
     if (contentType.includes("json")) {
@@ -169,8 +181,14 @@ export function fetchTransport(timeoutMs = 45_000) {
                 method,
                 headers,
                 // Only send a body when there IS one: a literal `null` payload with a JSON
-                // content-type is rejected by several endpoints.
-                body: body === undefined ? undefined : JSON.stringify(body),
+                // content-type is rejected by several endpoints. A FormData goes through as it is —
+                // stringifying it yields "[object FormData]", which uploads nothing and reads as a
+                // product error rather than ours.
+                body: body === undefined
+                    ? undefined
+                    : body instanceof FormData
+                        ? body
+                        : JSON.stringify(body),
                 // A redirect from an authenticated API is usually a login bounce, and following it
                 // turns a clear 401/302 into a 200 carrying an HTML sign-in page — which the
                 // resolver would then read as an empty result set rather than a failure.

package/dist/tools/capability-registry/index-loader.d.ts

@@ -10,6 +10,16 @@ export declare class IndexError extends Error {
 }
 /** Thrown to the caller as a tool error, so the wording is caller-facing. */
 export declare class InvocationError extends Error {
+    /**
+     * Set when the handle exists in the artifact but this surface withholds it.
+     *
+     * The MESSAGE deliberately does not say so — a caller is told the capability does not
+     * exist, because "withheld" invites a retry, a search for synonyms, or a question to the
+     * user about enabling it, none of which can succeed here. The flag keeps the distinction
+     * for telemetry, where knowing how often a withheld handle is reached for is how we learn
+     * whether withholding it was the right call.
+     */
+    withheld?: boolean;
 }
 /** The file inside a product subdirectory, for the earlier nested layout. */
 export declare const INDEX_FILE = "index.json";
@@ -32,8 +42,22 @@ export declare function endpointKey(method: string, path: string): string;
  * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
  * suppress something that cannot work, so an unexpected shape must hide it rather than be
  * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ *
+ * `local_only` withholds on a remote server only, for a capability that reads the caller's
+ * own machine: there, the path it would take resolves against the operator's disk instead.
+ * Read at call time rather than captured, because the remote server builds its config per
+ * session and a value captured at module load would outlive the deployment it described.
  */
 export declare function isDisabled(capability: Capability): boolean;
+/**
+ * Is this capability published for reference only on this surface?
+ *
+ * `local_only` on a remote server. The capability is real and the caller may well be asking
+ * for exactly it, so hiding it leaves the agent concluding no such route exists. Publishing
+ * it without the means to call it, and with a note saying what to do instead, answers the
+ * question it was asked.
+ */
+export declare function isReferenceOnly(capability: Capability): boolean;
 export interface LoadedProduct {
     name: string;
     product: ProductIndex;
@@ -66,16 +90,18 @@ export declare class CapabilityRegistry {
     private readonly withheld;
     constructor(index: RegistryIndex, provenance?: Record<string, Provenance>);
     /**
-     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     * Does this build withhold the handle?
      *
-     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
-     * with the decision; repeating it here would put four copies of a paragraph in the
-     * shipped artifact to serve a path the flag itself makes rare.
+     * WHAT THE CALLER IS TOLD IS THAT IT DOES NOT EXIST, which is why this returns a boolean
+     * rather than a message. Saying "withheld" describes the artifact rather than the
+     * surface, and every action it invites — retry, hunt for a synonym, ask the user to turn
+     * it on — fails here. A capability absent from search, describe and every listing should
+     * read the same way at invocation as it does everywhere else.
      *
-     * Returns undefined for anything else, so the caller falls through to its own
-     * not-found wording.
+     * The caller raises its own not-found error and marks it `withheld`, so the distinction
+     * survives in telemetry without reaching the agent.
      */
-    private withheldMatch;
+    private isWithheld;
     /** How many capabilities each product withholds. Startup logging only. */
     disabledCounts(): Record<string, number>;
     static fromFile(file: string): CapabilityRegistry;