fix: Gate call-actor mentions when the tool is absent from the session

Several places named call-actor unconditionally regardless of whether a
session's ?tools=/?actors= selection actually included it \u2014 inviting a
hallucinated call to a tool the client never received in tools/list.

- actor_tools_factory.ts: gate the call-actor line in dedicated Actor
  tool descriptions via the existing hasTool pattern.
- server-instructions/index.ts: getServerInstructions now takes a
  ToolDescriptionContext instead of a bare reportProblemAvailable
  boolean, gating every call-actor, rag-web-browser, web-fetch and
  report-problem mention through one mechanism.
- mcp/server.ts: legacy path passes the real per-session tool set;
  stateless path resolves call-actor presence from the request URL
  (?tools=/?actors=) with zero network calls, since that presence
  never depends on mode, client identity, or the Actor-metadata
  fetch \u2014 falls back to today's behavior when no URL is given.
- stateless_server.ts / dev_server.ts: thread requestUrl through,
  additive and backward compatible.

Adds a regression test pinning the Claude-connector tool surface
(19 tools, no call-actor) and asserting the resolved instructions
never mention it.

Author: MQ37

src/dev_server.ts

@@ -197,7 +197,7 @@ async function serveStatelessRequest(req: Request, res: Response, taskStore: InM
             if (!isDiscoverProbe) {
                 await mcpServer.loadToolsFromUrl(req.url, new ApifyClient({ token: apifyToken }));
             }
-            return createStatelessServer(mcpServer);
+            return createStatelessServer(mcpServer, req.url);
         },
         {
             legacy: 'reject',

src/mcp/server.ts

@@ -270,23 +270,30 @@ export class ActorsMcpServer implements LegacyMcpServerHost, StatelessMcpServerH
         await this.resolveInstanceWidgets();
     }
 
-    /**
-     * Server instructions for the current connection: mode plus whether report-problem is loaded.
-     * Read by the legacy adapter after `applyInitialize`, when the tool set is final.
-     */
+    /** Instructions for the current connection; `this.tools` is final here, after `applyInitialize`. */
     public getServerInstructions(): string {
-        return getServerInstructions(this.serverMode, this.tools.has(HELPER_TOOLS.PROBLEM_REPORT));
+        return getServerInstructions(this.serverMode, { hasTool: (name) => this.tools.has(name) });
     }
 
     /**
-     * Instructions for a stateless serving unit. The SDK answers `server/discover` from them before
-     * any request's envelope is seen, so they are configuration-level: no report-problem mention
-     * (that tool's presence is decided per request) and the configured mode only. Reads
-     * `serverModeOption`, never `_serverMode` — one facade serves both eras, and a legacy
-     * `initialize` rewrites `_serverMode`, which must not leak into later stateless requests.
+     * Instructions for a stateless serving unit, answered from `server/discover` before any request
+     * is seen — configuration-level only. Reads `serverModeOption`, never `_serverMode` (a legacy
+     * `initialize` must not leak its mode into later stateless requests).
+     *
+     * `requestUrl`, when given, sharpens only `call-actor`: its presence resolves from
+     * `?tools=`/`?actors=` with no fetch, unlike Actor tools or `report-problem` (identity-dependent).
+     * Without a match, `call-actor` is assumed present — today's behavior, unchanged.
      */
-    public getStatelessServerInstructions(): string {
-        return getServerInstructions(resolveServerMode(this.serverModeOption, false));
+    public getStatelessServerInstructions(requestUrl?: string): string {
+        const mode = resolveServerMode(this.serverModeOption, false);
+        if (requestUrl === undefined) {
+            return getServerInstructions(mode, { hasTool: (name) => name === HELPER_TOOLS.ACTOR_CALL });
+        }
+        const input = parseInputParamsFromUrl(requestUrl);
+        const toolNames = new Set(getToolsForServerMode(input, [], mode).map((tool) => tool.name));
+        return getServerInstructions(mode, {
+            hasTool: (name) => name === HELPER_TOOLS.ACTOR_CALL && toolNames.has(name),
+        });
     }
 
     /**

src/mcp/stateless_server.ts

@@ -75,7 +75,7 @@ export interface StatelessMcpServerHost {
     readonly options: ActorsMcpServerOptions;
     readonly promptService: ReturnType<typeof createPromptService>;
     resolveApifyToken(meta?: ApifyRequestParams['_meta']): string | undefined;
-    getStatelessServerInstructions(): string;
+    getStatelessServerInstructions(requestUrl?: string): string;
     createRequestSnapshot(clientContext: McpClientContext | undefined): Promise<StatelessRequestSnapshot>;
 }
 
@@ -125,7 +125,7 @@ class StatelessMcpServer {
      */
     private snapshot: Promise<StatelessRequestSnapshot> | undefined;
 
-    constructor(host: StatelessMcpServerHost) {
+    constructor(host: StatelessMcpServerHost, requestUrl?: string) {
         this.host = host;
         this.server = new Server(getServerInfo(), {
             capabilities: {
@@ -138,7 +138,7 @@ class StatelessMcpServer {
                 resources: {},
                 prompts: {},
             },
-            instructions: this.host.getStatelessServerInstructions(),
+            instructions: this.host.getStatelessServerInstructions(requestUrl),
         });
         this.setupToolHandlers();
         this.setupResourceHandlers();
@@ -391,7 +391,10 @@ async function emitLogServerSide(msg: { level: string; data?: unknown }): Promis
  * ```ts
  * const handler = createMcpHandler(() => createStatelessServer(actorsMcpServer), { legacy: 'reject' });
  * ```
+ *
+ * `requestUrl` sharpens the served instructions' `call-actor` mention; omit it for unchanged
+ * behavior.
  */
-export function createStatelessServer(host: StatelessMcpServerHost): Server {
-    return new StatelessMcpServer(host).server;
+export function createStatelessServer(host: StatelessMcpServerHost, requestUrl?: string): Server {
+    return new StatelessMcpServer(host, requestUrl).server;
 }

src/tools/actors/actor_tools_factory.ts

@@ -23,9 +23,11 @@ import {
     type ActorStore,
     type ActorTool,
     type ApifyToken,
+    type ToolDescriptionContext,
     type ToolEntry,
     type ToolInputSchema,
     ACTOR_TOOL_MODE,
+    ALL_TOOLS_PRESENT,
     TOOL_TYPE,
 } from '../../types.js';
 import { getActorDefinitionCached } from '../../utils/actor.js';
@@ -125,14 +127,17 @@ export async function getNormalActorsAsTools(
             waitSecs: WAIT_SECS_INPUT_PROPERTY,
         };
 
-        let description = `This tool calls the Actor "${definition.actorFullName}" and retrieves its output results.
-Use this tool instead of the "${HELPER_TOOLS.ACTOR_CALL}" if user requests this specific Actor.
-Actor description: ${definition.description}`;
-        if (isRag) {
-            description += `\n\n${RAG_WEB_BROWSER_ADDITIONAL_DESC}`;
-        } else if (definition.actorFullName === WEB_FETCH) {
-            description += `\n\n${WEB_FETCH_ADDITIONAL_DESC}`;
-        }
+        // Names call-actor only when the session actually has it.
+        const buildDescription = ({ hasTool }: ToolDescriptionContext): string => {
+            let description = `This tool calls the Actor "${definition.actorFullName}" and retrieves its output results.
+${hasTool(HELPER_TOOLS.ACTOR_CALL) ? `Use this tool instead of the "${HELPER_TOOLS.ACTOR_CALL}" if user requests this specific Actor.\n` : ''}Actor description: ${definition.description}`;
+            if (isRag) {
+                description += `\n\n${RAG_WEB_BROWSER_ADDITIONAL_DESC}`;
+            } else if (definition.actorFullName === WEB_FETCH) {
+                description += `\n\n${WEB_FETCH_ADDITIONAL_DESC}`;
+            }
+            return description;
+        };
 
         const memoryMbytes = Math.min(
             definition.defaultRunOptions?.memoryMbytes || ACTOR_MAX_MEMORY_MBYTES,
@@ -160,7 +165,8 @@ Actor description: ${definition.description}`;
             title: definition.actorFullName,
             actorId: definition.id,
             actorFullName: definition.actorFullName,
-            description,
+            description: buildDescription(ALL_TOOLS_PRESENT),
+            buildDescription,
             inputSchema: inputSchema as ToolInputSchema,
             // Canonical RunResponse shape — same as call-actor and get-actor-run.
             outputSchema: actorRunOutputSchema,

src/utils/server-instructions/index.ts

@@ -9,18 +9,22 @@
 
 import { getApifyAPIBaseUrl } from '../../apify_client.js';
 import { HELPER_TOOLS, RAG_WEB_BROWSER, WEB_FETCH } from '../../const.js';
-import { SERVER_MODE } from '../../types.js';
+import { actorNameToToolName } from '../../tools/actor_tool_naming.js';
+import type { ToolDescriptionContext } from '../../types.js';
+import { ALL_TOOLS_PRESENT, SERVER_MODE } from '../../types.js';
+
+// hasTool checks registered tool names, not Actor full names — see call_actor.ts's RAG_WEB_BROWSER_TOOL.
+const RAG_WEB_BROWSER_TOOL = actorNameToToolName(RAG_WEB_BROWSER);
+const WEB_FETCH_TOOL = actorNameToToolName(WEB_FETCH);
 
 /**
- * Build server instructions for the given mode.
- *
- * Apps-only sections are omitted in default mode to prevent models from
- * attempting to call widget tools that are not registered. The report-problem line is
- * emitted only when `reportProblemAvailable` is true — i.e. `report-problem` is actually
- * served — so clients that never receive the tool (Anthropic surfaces, telemetry off, or a
- * `tools=` selection that omits report-problem) are not told to call it.
+ * Build server instructions for the given mode. Every cross-tool mention is gated on
+ * `ctx.hasTool(...)` so a session missing a tool is never told to call it.
  */
-export function getServerInstructions(mode: SERVER_MODE = SERVER_MODE.DEFAULT, reportProblemAvailable = false): string {
+export function getServerInstructions(
+    mode: SERVER_MODE = SERVER_MODE.DEFAULT,
+    { hasTool }: ToolDescriptionContext = ALL_TOOLS_PRESENT,
+): string {
     const isApps = mode === SERVER_MODE.APPS;
     // Derive the API base from config so examples match the gate/templates under an
     // APIFY_API_BASE_URL / staging override, instead of a hardcoded api.apify.com.
@@ -70,13 +74,20 @@ ${
 ## Widget workflow (applies when tool responses include widget metadata)
 Some clients render widget-backed Actor tools: the response includes a live UI that automatically polls run status. When a widget is rendered, follow-up status polling by the model is a forbidden duplicate.
 
-- **After \`${HELPER_TOOLS.ACTOR_CALL_WIDGET}\` or \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\`, never call \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` or \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` for the same run.** Both widgets render live progress and poll themselves — stop after the widget response and defer to it for run status. Re-rendering the same run via \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` is a duplicate.
+${
+    hasTool(HELPER_TOOLS.ACTOR_CALL)
+        ? `- **After \`${HELPER_TOOLS.ACTOR_CALL_WIDGET}\` or \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\`, never call \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` or \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` for the same run.** Both widgets render live progress and poll themselves — stop after the widget response and defer to it for run status. Re-rendering the same run via \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` is a duplicate.
 - Polling \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` after \`${HELPER_TOOLS.ACTOR_CALL}\` is fine — that tool renders no UI, so polling is expected when the run is non-terminal and you need the latest status.
 `
+        : `- **After \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\`, never call \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` or \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` for the same run.** It renders live progress and polls itself — stop after the widget response and defer to it for run status. Re-rendering the same run via \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` is a duplicate.
+`
+}`
         : ''
 }
 ## Tool dependencies and disambiguation
-
+${
+    hasTool(HELPER_TOOLS.ACTOR_CALL)
+        ? `
 ### Tool dependencies
 - \`${HELPER_TOOLS.ACTOR_CALL}\`:
   - Use \`${HELPER_TOOLS.ACTOR_GET_DETAILS}\` first to obtain the Actor's input schema.
@@ -85,7 +96,9 @@ Some clients render widget-backed Actor tools: the response includes a live UI t
   - Supports a \`waitSecs\` parameter (default 30, max 45):
     - \`waitSecs: 0\`: fire-and-forget — starts the run and returns immediately with a runId.
     - \`waitSecs > 0\`: waits up to that many seconds for the run to complete, then returns its current status and storage IDs (never the output rows — fetch those with \`${HELPER_TOOLS.DATASET_GET_ITEMS}\`).
-
+`
+        : ''
+}
 ### Tool disambiguation
 - **\`${HELPER_TOOLS.STORE_SEARCH}\` vs \`${HELPER_TOOLS.ACTOR_GET_DETAILS}\`:**
   \`${HELPER_TOOLS.STORE_SEARCH}\` finds Actors; \`${HELPER_TOOLS.ACTOR_GET_DETAILS}\` retrieves detailed info, README, and schema for a specific Actor.
@@ -94,22 +107,33 @@ ${
         ? `- **Data vs widget Actor tools (when the client supports widgets):**
   - \`${HELPER_TOOLS.STORE_SEARCH}\` is a silent data lookup (Actor list for name resolution) with no UI; \`${HELPER_TOOLS.STORE_SEARCH_WIDGET}\` renders an interactive UI element (widget) with Actor search results for the user to browse — use it only when the user explicitly asks to search or discover Actors.
   - \`${HELPER_TOOLS.ACTOR_GET_DETAILS}\` is a silent data lookup (input schema, README, metadata) with no UI; \`${HELPER_TOOLS.ACTOR_GET_DETAILS_WIDGET}\` renders an interactive UI element (widget) with Actor details — use it only when the user explicitly asks to see or browse the Actor.
-  - \`${HELPER_TOOLS.ACTOR_CALL}\` runs the Actor and returns its run status and storage IDs (no UI); \`${HELPER_TOOLS.ACTOR_CALL_WIDGET}\` renders an interactive UI element (widget) that tracks live Actor run progress — use it only when the user explicitly asks to see progress.
-  - \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` is a silent data lookup (run status, dataset IDs, stats) with no UI; \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` renders an interactive UI element (widget) showing live run progress for the user — use it only when the user explicitly asks to see run progress.
+${hasTool(HELPER_TOOLS.ACTOR_CALL) ? `  - \`${HELPER_TOOLS.ACTOR_CALL}\` runs the Actor and returns its run status and storage IDs (no UI); \`${HELPER_TOOLS.ACTOR_CALL_WIDGET}\` renders an interactive UI element (widget) that tracks live Actor run progress — use it only when the user explicitly asks to see progress.\n` : ''}  - \`${HELPER_TOOLS.ACTOR_RUNS_GET}\` is a silent data lookup (run status, dataset IDs, stats) with no UI; \`${HELPER_TOOLS.ACTOR_RUNS_GET_WIDGET}\` renders an interactive UI element (widget) showing live run progress for the user — use it only when the user explicitly asks to see run progress.
   - When the next step is running an Actor, prefer silent lookups (\`${HELPER_TOOLS.STORE_SEARCH}\`, \`${HELPER_TOOLS.ACTOR_GET_DETAILS}\`) over widget-backed variants.
 `
         : ''
-}- **\`${HELPER_TOOLS.STORE_SEARCH}\` vs ${RAG_WEB_BROWSER}:**
+}${
+        hasTool(RAG_WEB_BROWSER_TOOL)
+            ? `- **\`${HELPER_TOOLS.STORE_SEARCH}\` vs ${RAG_WEB_BROWSER}:**
   \`${HELPER_TOOLS.STORE_SEARCH}\` finds robust and reliable Actors for specific websites; ${RAG_WEB_BROWSER} is a general and versatile web scraping tool.
-- **${WEB_FETCH} vs ${RAG_WEB_BROWSER}:**
+`
+            : ''
+    }${
+        hasTool(WEB_FETCH_TOOL) && hasTool(RAG_WEB_BROWSER_TOOL)
+            ? `- **${WEB_FETCH} vs ${RAG_WEB_BROWSER}:**
   ${WEB_FETCH} fetches one specific URL and returns its full content verbatim; ${RAG_WEB_BROWSER} searches the web by query and returns content from the top results.
-- **Dedicated Actor tools (e.g. ${RAG_WEB_BROWSER}) vs \`${HELPER_TOOLS.ACTOR_CALL}\`:**
+`
+            : ''
+    }${
+        hasTool(HELPER_TOOLS.ACTOR_CALL)
+            ? `- **Dedicated Actor tools${hasTool(RAG_WEB_BROWSER_TOOL) ? ` (e.g. ${RAG_WEB_BROWSER})` : ''} vs \`${HELPER_TOOLS.ACTOR_CALL}\`:**
   Prefer dedicated tools when available; use \`${HELPER_TOOLS.ACTOR_CALL}\` only when no specialized tool exists in the Apify store.
-${
-    reportProblemAvailable
-        ? `
+`
+            : ''
+    }${
+        hasTool(HELPER_TOOLS.PROBLEM_REPORT)
+            ? `
 If a tool or Actor fails and you cannot resolve it, you can report it with \`${HELPER_TOOLS.PROBLEM_REPORT}\`.
 `
-        : ''
-}`;
+            : ''
+    }`;
 }