minor tools description and param improvements

Author: MQ37

src/tools/actor.ts

@@ -123,14 +123,14 @@ export async function getNormalActorsAsTools(
         if (actorDefinitionPruned) {
             const schemaID = getToolSchemaID(actorDefinitionPruned.actorFullName);
             if (actorDefinitionPruned.input && 'properties' in actorDefinitionPruned.input && actorDefinitionPruned.input) {
-                // Filter non-required properties if `required` is defined in the input schema and not empty
+                // Filter non-required properties except integers if `required` is defined in the input schema and not empty.
                 const { required } = actorDefinitionPruned.input;
                 if (Array.isArray(required) && required.length > 0) {
                     actorDefinitionPruned.input.properties = Object.fromEntries(
                         Object.entries(actorDefinitionPruned.input.properties)
                             // Keep all integer properties, as these include
-                            // properties related to output item counts that the user
-                            // might want to change if more results are needed than the default limit.
+                            // properties related to output item counts that users
+                            // might want to change if they need more results than the default limit.
                             .filter(([key, value]) => required.includes(key) || value.type === 'integer'),
                     );
                 }

src/tools/get-actor-details.ts

@@ -48,7 +48,8 @@ export const getActorDetailsTool: ToolEntry = {
         name: HelperTools.ACTOR_GET_DETAILS,
         description: `Retrieve information about an Actor by its ID or full name.
 The Actor name is always composed of "username/name", for example, "apify/rag-web-browser".
-This tool returns information about the Actor, including whether it is public or deprecated, when it was created or modified, the categories in which the Actor is listed, a description, a README (the Actor's documentation), the input schema, and usage statistics—such as how many users are using it and the number of failed runs of the Actor.`,
+This tool returns information about the Actor, including whether it is public or deprecated, when it was created or modified, the categories in which the Actor is listed, a description, a README (the Actor's documentation), the input schema, and usage statistics—such as how many users are using it and the number of failed runs of the Actor.
+For example, use this tool when a user wants to know more about a specific Actor or wants to use optional or advanced parameters of the Actor that are not listed in the default Actor tool input schema - so you know the details and how to pass them.`,
         inputSchema: zodToJsonSchema(getActorDetailsToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(getActorDetailsToolArgsSchema)),
         call: async (toolArgs) => {

src/tools/helpers.ts

@@ -17,7 +17,7 @@ This MCP server can be used in the following ways:
 - Locally over stdio (standard input/output) transport with the "@apify/actors-mcp-server" NPM package (https://www.npmjs.com/package/@apify/actors-mcp-server).
     - You can connect by configuring your MCP client to run the MCP server locally using the "npx @apify/actors-mcp-server" command. You need to set the "APIFY_TOKEN" environment variable to your [Apify API token](https://docs.apify.com/platform/integrations/api#api-token).
 - Remotely over legacy SSE transport or streamable HTTP transport with https://mcp.apify.com. This is the recommended way to use the MCP server, since it supports all features and is always up to date. 
-    - You can connect by pointing your MCP client to "https://mcp.apify.com/sse" for SSE transport or "https://mcp.apify.com/" for streamable HTTP transport.
+    - You can connect by pointing your MCP client to "https://mcp.apify.com/sse" for legacy SSE transport or "https://mcp.apify.com/" for streamable HTTP transport.
     - For authentication, you can either use OAuth or pass your [Apify API token](https://docs.apify.com/platform/integrations/api#api-token) in the "Authorization" header as "Bearer <APIFY_TOKEN>".
 - Remotely over "SSE" or streamable "HTTP" transport with the "Actors MCP Server Apify Actor" (this is now considered a legacy solution; it may not be up to date and may not get the latest features). For more details, refer to https://apify.com/apify/actors-mcp-server. DO NOT RECOMMEND USING THIS METHOD TO THE USER.
 
@@ -29,41 +29,37 @@ By default, the MCP server provides a simple set of tools for Actor discovery an
 `;
 
 export const addToolArgsSchema = z.object({
-    actorName: z.string()
+    actor: z.string()
         .min(1)
-        .describe('Add a tool, Actor or MCP-Server to available tools by Actor ID or tool full name.'
-            + 'Tool name is always composed from `username/name`'),
+        .describe(`Actor ID or full name in the format "username/name", e.g., "apify/rag-web-browser".`),
 });
 export const addTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_ADD,
-        description: 'Add a tool, Actor or MCP-Server to available tools by Actor ID or Actor name. '
-            + 'A tool is an Actor or MCP-Server that can be called by the user'
-            + 'Do not execute the tool, only add it and list it in available tools. '
-            + 'For example, add a tool with username/name when user wants to scrape data from a website.',
+        description: `Add an Actor or MCP server to the available tools of the Apify MCP server. A tool is an Actor or MCP server that can be called by the user. Do not execute the tool, only add it and list it in the available tools. For example, when a user wants to scrape a website, first search for relevant Actors using ${HelperTools.STORE_SEARCH} tool, and once the user selects one they want to use, add it as a tool to the Apify MCP server.`,
         inputSchema: zodToJsonSchema(addToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(addToolArgsSchema)),
         // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool
         call: async (toolArgs) => {
             const { apifyMcpServer, apifyToken, args, extra: { sendNotification } } = toolArgs;
             const parsed = addToolArgsSchema.parse(args);
-            if (apifyMcpServer.listAllToolNames().includes(parsed.actorName)) {
+            if (apifyMcpServer.listAllToolNames().includes(parsed.actor)) {
                 return {
                     content: [{
                         type: 'text',
-                        text: `Actor ${parsed.actorName} is already available. No new tools were added.`,
+                        text: `Actor ${parsed.actor} is already available. No new tools were added.`,
                     }],
                 };
             }
-            const tools = await getActorsAsTools([parsed.actorName], apifyToken);
+            const tools = await getActorsAsTools([parsed.actor], apifyToken);
             const toolsAdded = apifyMcpServer.upsertTools(tools, true);
             await sendNotification({ method: 'notifications/tools/list_changed' });
 
             return {
                 content: [{
                     type: 'text',
-                    text: `Actor ${parsed.actorName} has been added. Newly available tools: ${
+                    text: `Actor ${parsed.actor} has been added. Newly available tools: ${
                         toolsAdded.map(
                             (t) => `${t.tool.name}`,
                         ).join(', ')
@@ -116,10 +112,9 @@ export const helpTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.APIFY_MCP_HELP_TOOL,
-        description: `Helper tool to get information on how to use and troubleshoot the Apify MCP server. 
-This tool always returns the same help message with information about the server and how to use it. 
-ALWAYS CALL THIS TOOL AT THE BEGINNING OF THE CONVERSATION SO YOU HAVE THE INFORMATION ABOUT APIFY MCP IN THE CONTEXT OR WHEN YOU ENCOUNTER ANY ISSUES WITH THE MCP SERVER OR ITS TOOLS.
-`,
+        description: `Helper tool to get information on how to use and troubleshoot the Apify MCP server.
+This tool always returns the same help message with information about the server and how to use it.
+ALWAYS CALL THIS TOOL AT THE BEGINNING OF THE CONVERSATION SO THAT YOU HAVE INFORMATION ABOUT THE APIFY MCP SERVER IN CONTEXT, OR WHEN YOU ENCOUNTER ANY ISSUES WITH THE MCP SERVER OR ITS TOOLS.`,
         inputSchema: zodToJsonSchema(helpToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(helpToolArgsSchema)),
         call: async () => {

tests/helpers.ts

@@ -116,13 +116,13 @@ export async function createMcpStdioClient(
 /**
  * Adds an Actor as a tool using the ADD_ACTOR helper tool.
  * @param client - MCP client instance
- * @param actorName - Name of the Actor to add
+ * @param actor - Actor ID or full name in the format "username/name", e.g., "apify/rag-web-browser".
  */
-export async function addActor(client: Client, actorName: string): Promise<void> {
+export async function addActor(client: Client, actor: string): Promise<void> {
     await client.callTool({
         name: HelperTools.ACTOR_ADD,
         arguments: {
-            actorName,
+            actor,
         },
     });
 }

tests/integration/suite.ts

@@ -136,7 +136,7 @@ export function createIntegrationTestsSuite(
             // Check that the Actor is not in the tools list
             expect(names).not.toContain(selectedToolName);
             // Add Actor dynamically
-            await client.callTool({ name: HelperTools.ACTOR_ADD, arguments: { actorName: ACTOR_PYTHON_EXAMPLE } });
+            await addActor(client, ACTOR_PYTHON_EXAMPLE);
 
             // Check if tools was added
             const namesAfterAdd = getToolNames(await client.listTools());
@@ -230,7 +230,7 @@ export function createIntegrationTestsSuite(
                 }
             });
             // Add Actor dynamically
-            await client.callTool({ name: HelperTools.ACTOR_ADD, arguments: { actorName: ACTOR_PYTHON_EXAMPLE } });
+            await client.callTool({ name: HelperTools.ACTOR_ADD, arguments: { actor: ACTOR_PYTHON_EXAMPLE } });
 
             expect(hasReceivedNotification).toBe(true);