feat: Add tool annotations (#333)

* 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

* fix: Update README.md

* fix: add openWorldHint=false explicitly to relevant tools

Author: jirispilka

README.md

@@ -178,6 +178,14 @@ Here is an overview list of all the tools provided by the Apify MCP Server.
 
 > The `get-actor-output` tool is automatically included with any Actor-related tool, such as `call-actor`, `add-actor`, or any specific Actor tool like `apify-slash-rag-web-browser`. When you call an Actor - either through the `call-actor` tool or directly via an Actor tool (e.g., `apify-slash-rag-web-browser`) - you receive a preview of the output. The preview depends on the Actor's output format and length; for some Actors and runs, it may include the entire output, while for others, only a limited version is returned to avoid overwhelming the LLM. To retrieve the full output of an Actor run, use the `get-actor-output` tool (supports limit, offset, and field filtering) with the `datasetId` provided by the Actor call.
 
+### Tool annotations
+
+All tools include metadata annotations to help MCP clients and LLMs understand tool behavior:
+
+- **`title`**: Short display name for the tool (e.g., "Search Actors", "Call Actor", "apify/rag-web-browser")
+- **`readOnlyHint`**: `true` for tools that only read data without modifying state (e.g., `get-dataset`, `fetch-actor-details`)
+- **`openWorldHint`**: `true` for tools that access external resources outside the Apify platform (e.g., `call-actor` executes external Actors, `get-html-skeleton` scrapes external websites). Tools that interact only with the Apify platform (like `search-actors` or `fetch-apify-docs`) do not have this hint.
+
 ### Tools configuration
 
 The `tools` configuration parameter is used to specify loaded tools - either categories or specific tools directly, and Apify Actors. For example, `tools=storage,runs` loads two categories; `tools=add-actor` loads just one tool.

src/mcp/server.ts

@@ -298,8 +298,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

@@ -199,6 +199,10 @@ Actor description: ${actorDefinitionPruned.description}`;
             inputSchema: inputSchema as ToolInputSchema,
             ajvValidate,
             memoryMbytes,
+            annotations: {
+                title: actorDefinitionPruned.actorFullName,
+                openWorldHint: true,
+            },
         });
     }
     return tools;
@@ -375,6 +379,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

@@ -125,6 +125,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
 

src/tools/dataset.ts

@@ -57,6 +57,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetArgs.parse(args);
@@ -89,6 +94,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetItemsArgs.parse(args);
@@ -148,6 +158,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getDatasetSchemaArgs.parse(args);

src/tools/dataset_collection.ts

@@ -42,6 +42,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = getUserDatasetsListArgs.parse(args);

src/tools/fetch-actor-details.ts

@@ -29,6 +29,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken } = toolArgs;
         const parsed = fetchActorDetailsToolArgsSchema.parse(args);

src/tools/fetch-apify-docs.ts

@@ -28,6 +28,11 @@ 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,
+        openWorldHint: false,
+    },
     call: async (toolArgs: InternalToolArgs) => {
         const { args } = toolArgs;
 

src/tools/get-actor-output.ts

@@ -88,6 +88,11 @@ 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,
+        openWorldHint: false,
+    },
     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);