fix: Stop pointing non-Actor tools at fetch-actor-details (#1485)

## Why

Closes #1214

Invalid- and missing-arguments errors told every tool to inspect its
schema via `fetch-actor-details`. That tool only describes Actors and
may not be served, so for `search-apify-docs` and other non-Actor tools
the advice was dead.

## What changed

The pointer stays only for an Actor tool in a session that serves
`fetch-actor-details`, and that text is unchanged. Everything else now
points at the schema in `tools/list`.

Two additions beyond the issue: the missing-arguments message had the
same pointer, and an Actor tool without `fetch-actor-details` served got
the same dead advice.

## Notes for reviewers (human-written)
-

## Proof it works

Six new cases in `tool_call_engine.test.ts`; four failed before the fix.
Dropping either half of the condition fails only its own two cases.

```
Test Files  115 passed (115)
      Tests  2118 passed | 1 skipped (2119)
   Start at  11:43:23
   Duration  4.33s (transform 5.27s, setup 0ms, import 38.51s, tests 3.02s, environment 5ms)
```

co-written with Claude Code.

Author: daveomri

src/mcp/tool_call_engine.ts

@@ -175,12 +175,17 @@ export async function prepareToolCall(params: {
 
     const actorName = extractActorName(tool, args as Record<string, unknown>);
     const actorId = extractActorId(tool);
+    // fetch-actor-details only describes Actors, and only helps if this session serves it.
+    const schemaHint =
+        tool.type === TOOL_TYPE.ACTOR && tools.has(HELPER_TOOLS.ACTOR_GET_DETAILS)
+            ? `using ${HELPER_TOOLS.ACTOR_GET_DETAILS} tool`
+            : 'in tools/list';
 
     if (!args) {
         return {
             message: dedent`
                 Missing arguments for tool "${name}".
-                Please provide the required arguments for this tool. Check the tool's input schema using ${HELPER_TOOLS.ACTOR_GET_DETAILS} tool to see what parameters are required.
+                Please provide the required arguments for this tool. Check the tool's input schema ${schemaHint} to see what parameters are required.
             `,
             toolStatus: TOOL_STATUS.SOFT_FAIL,
             callDiagnostics: {
@@ -233,7 +238,7 @@ export async function prepareToolCall(params: {
                 message: dedent`
                     Invalid arguments for tool "${tool.name}".
                     Validation errors: ${errorMessages}.
-                    Please check the tool's input schema using ${HELPER_TOOLS.ACTOR_GET_DETAILS} tool and ensure all required parameters are provided with correct types and values.
+                    Please check the tool's input schema ${schemaHint} and ensure all required parameters are provided with correct types and values.
                 `,
                 toolStatus: TOOL_STATUS.SOFT_FAIL,
                 callDiagnostics: {

tests/unit/tool_call_engine.test.ts

@@ -2,11 +2,15 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import log from '@apify/log';
 
-import { FAILURE_CATEGORY, TOOL_STATUS } from '../../src/const.js';
+import { FAILURE_CATEGORY, HELPER_TOOLS, TOOL_STATUS } from '../../src/const.js';
 import type { ActorsMcpServer } from '../../src/mcp/server.js';
 import type { InvalidToolCall, PreparedCall } from '../../src/mcp/tool_call_engine.js';
 import { executeSyncToolCall, prepareToolCall } from '../../src/mcp/tool_call_engine.js';
-import type { ToolCallTelemetryProperties } from '../../src/types.js';
+import { fetchActorDetails } from '../../src/tools/actors/fetch_actor_details.js';
+import type { ToolCallTelemetryProperties, ToolEntry, ToolInputSchema } from '../../src/types.js';
+import { TOOL_TYPE } from '../../src/types.js';
+import { compileSchema } from '../../src/utils/ajv.js';
+import { respondRaw } from '../../src/utils/mcp.js';
 import { makePaymentRequiredError, makeRecorderTool, makeThrowingTool, withServer } from './helpers/mcp_server.js';
 
 /** An abort signal for direct engine tests, optionally already aborted. */
@@ -126,6 +130,75 @@ describe('prepareToolCall()', () => {
             expect(telemetryData.tool_name).toBe('recorder-tool');
         });
     });
+
+    describe('argument failure hint', () => {
+        const STRICT_SCHEMA = {
+            type: 'object',
+            properties: { query: { type: 'string', minLength: 1 } },
+            required: ['query'],
+        };
+
+        function makeStrictTool(type: typeof TOOL_TYPE.INTERNAL | typeof TOOL_TYPE.ACTOR): ToolEntry {
+            const base = {
+                name: 'strict-tool',
+                description: 'requires a non-empty query',
+                inputSchema: STRICT_SCHEMA as ToolInputSchema,
+                ajvValidate: compileSchema(STRICT_SCHEMA),
+            };
+            return type === TOOL_TYPE.ACTOR
+                ? { ...base, type, actorId: 'actor-id-1', actorFullName: 'apify/strict-actor' }
+                : { ...base, type, call: async () => respondRaw({ content: [] }) };
+        }
+
+        // The map is built per case, so each one controls exactly whether fetch-actor-details is served.
+        async function failureMessage(
+            tool: ToolEntry,
+            fetchActorDetailsServed: boolean,
+            args: Record<string, unknown> | undefined,
+        ): Promise<string> {
+            const tools = new Map<string, ToolEntry>([[tool.name, tool]]);
+            if (fetchActorDetailsServed) tools.set(HELPER_TOOLS.ACTOR_GET_DETAILS, fetchActorDetails);
+            const result = await prepareToolCall({
+                tools,
+                apifyToken: 'fake-token',
+                name: tool.name,
+                args,
+                meta: undefined,
+                requestHeaders: undefined,
+                isTaskRequest: false,
+                mcpSessionId: 's1',
+                telemetryData: null,
+                clientContext: undefined,
+            });
+            expect('message' in result).toBe(true);
+            return (result as InvalidToolCall).message;
+        }
+
+        describe.each([
+            ['invalid', { query: '' }],
+            ['missing', undefined],
+        ])('%s arguments', (_label, args) => {
+            it('points a non-Actor tool at its tools/list schema, not fetch-actor-details', async () => {
+                const message = await failureMessage(makeStrictTool(TOOL_TYPE.INTERNAL), true, args);
+
+                expect(message).not.toContain(HELPER_TOOLS.ACTOR_GET_DETAILS);
+                expect(message).toContain('tools/list');
+            });
+
+            it('points an Actor tool at fetch-actor-details when the session serves it', async () => {
+                const message = await failureMessage(makeStrictTool(TOOL_TYPE.ACTOR), true, args);
+
+                expect(message).toContain(HELPER_TOOLS.ACTOR_GET_DETAILS);
+            });
+
+            it('points an Actor tool at tools/list when fetch-actor-details is not served', async () => {
+                const message = await failureMessage(makeStrictTool(TOOL_TYPE.ACTOR), false, args);
+
+                expect(message).not.toContain(HELPER_TOOLS.ACTOR_GET_DETAILS);
+                expect(message).toContain('tools/list');
+            });
+        });
+    });
 });
 
 describe('executeSyncToolCall()', () => {