feat: Add tool annotations (title, readOnlyHint, openWorldHint)

Add annotations to all internal and Actor tools:
- title: Short display name (sentence case, Actor/Apify capitalized)
- readOnlyHint: true for read-only tools
- openWorldHint: true only for tools accessing open world (external web/Actors), not Apify platform

Examples: call-actor and get-html-skeleton are openWorld; search-actors and fetch-apify-docs are not

Author: jirispilka

src/mcp/server.ts

@@ -297,8 +297,8 @@ export class ActorsMcpServer {
             }
         } else {
             // No skyfire mode - store tools as-is
-            for (const wrap of tools) {
-                this.tools.set(wrap.name, wrap);
+            for (const tool of tools) {
+                this.tools.set(tool.name, tool);
             }
         }
         if (shouldNotifyToolsChangedHandler) this.notifyToolsChangedHandler();

src/tools/actor.ts

@@ -198,6 +198,10 @@ Actor description: ${actorDefinitionPruned.description}`;
             inputSchema: inputSchema as ToolInputSchema,
             ajvValidate,
             memoryMbytes,
+            annotations: {
+                title: actorDefinitionPruned.actorFullName,
+                openWorldHint: true,
+            },
         });
     }
     return tools;
@@ -361,6 +365,10 @@ EXAMPLES:
         // Additional props true to allow skyfire-pay-id
         additionalProperties: true,
     }),
+    annotations: {
+        title: 'Call Actor',
+        openWorldHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken, progressTracker, extra, apifyMcpServer } = toolArgs;
         const { actor: actorName, step, input, callOptions } = callActorArgs.parse(args);

src/tools/build.ts

@@ -116,6 +116,10 @@ export const actorDefinitionTool: ToolEntry = {
         + `Limit the length of the README if needed.`,
     inputSchema: zodToJsonSchema(getActorDefinitionArgsSchema) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getActorDefinitionArgsSchema)),
+    annotations: {
+        title: 'Get Actor definition',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
 

src/tools/dataset.ts

@@ -57,6 +57,10 @@ USAGE EXAMPLES:
 - user_input: What fields does username~my-dataset have?`,
     inputSchema: zodToJsonSchema(getDatasetArgs) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getDatasetArgs)),
+    annotations: {
+        title: 'Get dataset',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetArgs.parse(args);
@@ -89,6 +93,10 @@ USAGE EXAMPLES:
 - user_input: Get only metadata.url and title from dataset username~my-dataset (flatten metadata)`,
     inputSchema: zodToJsonSchema(getDatasetItemsArgs) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getDatasetItemsArgs)),
+    annotations: {
+        title: 'Get dataset items',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetItemsArgs.parse(args);
@@ -148,6 +156,10 @@ USAGE EXAMPLES:
 - user_input: Show schema of username~my-dataset (clean items only)`,
     inputSchema: zodToJsonSchema(getDatasetSchemaArgs) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getDatasetSchemaArgs)),
+    annotations: {
+        title: 'Get dataset schema',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetSchemaArgs.parse(args);

src/tools/dataset_collection.ts

@@ -42,6 +42,10 @@ USAGE EXAMPLES:
 - user_input: List unnamed datasets`,
     inputSchema: zodToJsonSchema(getUserDatasetsListArgs) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getUserDatasetsListArgs)),
+    annotations: {
+        title: 'Get user datasets list',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getUserDatasetsListArgs.parse(args);

src/tools/fetch-actor-details.ts

@@ -29,6 +29,10 @@ USAGE EXAMPLES:
 - user_input: What is the pricing for apify/instagram-scraper?`,
     inputSchema: zodToJsonSchema(fetchActorDetailsToolArgsSchema) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(fetchActorDetailsToolArgsSchema)),
+    annotations: {
+        title: 'Fetch Actor details',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = fetchActorDetailsToolArgsSchema.parse(args);

src/tools/fetch-apify-docs.ts

@@ -29,6 +29,10 @@ USAGE EXAMPLES:
 - user_input: Fetch https://docs.apify.com/academy`,
     inputSchema: zodToJsonSchema(fetchApifyDocsToolArgsSchema) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(fetchApifyDocsToolArgsSchema)),
+    annotations: {
+        title: 'Fetch Apify docs',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args } = toolArgs;
 

src/tools/get-actor-output.ts

@@ -88,6 +88,10 @@ Note: This tool is automatically included if the Apify MCP Server is configured
      * Allow additional properties for Skyfire mode to pass `skyfire-pay-id`.
      */
     ajvValidate: ajv.compile({ ...zodToJsonSchema(getActorOutputArgs), additionalProperties: true }),
+    annotations: {
+        title: 'Get Actor output',
+        readOnlyHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken, apifyMcpServer } = toolArgs;
 

src/tools/get-html-skeleton.ts

@@ -52,6 +52,11 @@ USAGE EXAMPLES:
 - user_input: Get next chunk of HTML skeleton for https://example.com (chunk=2)`,
     inputSchema: zodToJsonSchema(getHtmlSkeletonArgs) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(getHtmlSkeletonArgs)),
+    annotations: {
+        title: 'Get HTML skeleton',
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getHtmlSkeletonArgs.parse(args);

src/tools/helpers.ts

@@ -27,6 +27,9 @@ USAGE EXAMPLES:
 - user_input: Add apify/instagram-scraper as a tool`,
     inputSchema: zodToJsonSchema(addToolArgsSchema) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(addToolArgsSchema)),
+    annotations: {
+        title: 'Add tool',
+    },
     // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool
     call: async (toolArgs: InternalToolArgs) => {
         const { apifyMcpServer, apifyToken, args, extra: { sendNotification } } = toolArgs;