fix: Add idempotentHint annotations to various tools. For Actors, the destructiveHint is set to true as an Actor can perform any type of operation at Apify platform (#381)

Author: jirispilka

src/mcp/proxy.ts

@@ -27,6 +27,8 @@ export async function getMCPServerTools(
             description: tool.description || '',
             inputSchema: tool.inputSchema,
             ajvValidate: fixedAjvCompile(ajv, tool.inputSchema),
+            // Preserve annotations from the proxied tool
+            annotations: tool.annotations,
         };
 
         compiledTools.push(mcpTool);

src/tools/actor.ts

@@ -202,10 +202,11 @@ Actor description: ${definition.description}`;
                 : undefined,
             annotations: {
                 title: definition.actorFullName,
-                destructiveHint: false,
+                readOnlyHint: false,
+                destructiveHint: true,
                 openWorldHint: true,
             },
-            // Allow long running tasks for Actor tools, make it optional for now
+            // Allow long-running tasks for Actor tools, make it optional for now
             execution: {
                 taskSupport: 'optional',
             },
@@ -220,7 +221,7 @@ async function getMCPServersAsTools(
 ): Promise<ToolEntry[]> {
     /**
      * This is case for the Skyfire request without any Apify token, we do not support
-     * standby Actors in this case so we can skip MCP servers since they would fail anyway (they are standby Actors).
+     * standby Actors in this case, so we can skip MCP servers since they would fail anyway (they are standby Actors).
     */
     if (apifyToken === null || apifyToken === undefined) {
         return [];
@@ -387,15 +388,17 @@ Step 2: Call Actor (step="call")
 EXAMPLES:
 - user_input: Get instagram posts using apify/instagram-scraper`,
     inputSchema: z.toJSONSchema(callActorArgs) as ToolInputSchema,
-    // For now we are not adding the strucuted output schema since this tool is quite complex and has multiple possible ends states
+    // For now we are not adding the structured output schema since this tool is quite complex and has multiple possible ends states
     ajvValidate: compileSchema({
         ...z.toJSONSchema(callActorArgs),
         // Additional props true to allow skyfire-pay-id
         additionalProperties: true,
     }),
     annotations: {
         title: 'Call Actor',
-        destructiveHint: false,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
         openWorldHint: true,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/dataset.ts

@@ -60,6 +60,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get dataset',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
@@ -101,6 +102,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get dataset items',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
@@ -169,6 +171,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get dataset schema',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/dataset_collection.ts

@@ -44,6 +44,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get user datasets list',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/fetch-actor-details.ts

@@ -34,6 +34,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Fetch Actor details',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/fetch-apify-docs.ts

@@ -36,6 +36,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Fetch Apify docs',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/get-actor-output.ts

@@ -91,6 +91,7 @@ Note: This tool is automatically included if the Apify MCP Server is configured
     annotations: {
         title: 'Get Actor output',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/get-html-skeleton.ts

@@ -54,6 +54,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get HTML skeleton',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: true,
     },
     call: async (toolArgs: InternalToolArgs) => {

src/tools/helpers.ts

@@ -28,7 +28,9 @@ USAGE EXAMPLES:
     ajvValidate: compileSchema(z.toJSONSchema(addToolArgsSchema)),
     annotations: {
         title: 'Add tool',
+        readOnlyHint: false,
         destructiveHint: false,
+        idempotentHint: true,
         openWorldHint: true,
     },
     // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool

src/tools/key_value_store.ts

@@ -31,6 +31,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get key-value store',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
@@ -76,6 +77,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get key-value store keys',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
@@ -119,6 +121,7 @@ USAGE EXAMPLES:
     annotations: {
         title: 'Get key-value store record',
         readOnlyHint: true,
+        idempotentHint: true,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {