chore: update n8n to 2.1.5 and bump version to 2.31.6 (#521 )

- Updated n8n from 2.1.4 to 2.1.5 - Updated n8n-core from 2.1.3 to 2.1.4 - Updated @n8n/n8n-nodes-langchain from 2.1.3 to 2.1.4 - Rebuilt node database with 540 nodes (434 from n8n-nodes-base, 106 from @n8n/n8n-nodes-langchain) - Updated README badge with new n8n version - Updated CHANGELOG with dependency changes Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Romuald Członkowski <romualdczlonkowski@MacBook-Pro-Romuald.local> Co-authored-by: Claude <noreply@anthropic.com>
feat: add MCP tool annotations to all 20 tools (#512 )
2026-01-30 22:42:04 +00:00 · 2026-01-04 10:43:35 +01:00 · 2026-01-02 15:48:47 +01:00
8 changed files with 240 additions and 71 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [2.31.6] - 2026-01-03
+
+### Changed
+
+**Dependencies Update**
+
+- Updated n8n from 2.1.4 to 2.1.5
+- Updated n8n-core from 2.1.3 to 2.1.4
+- Updated @n8n/n8n-nodes-langchain from 2.1.3 to 2.1.4
+- Rebuilt node database with 540 nodes (434 from n8n-nodes-base, 106 from @n8n/n8n-nodes-langchain)
+
+## [2.31.5] - 2026-01-02
+
+### Added
+
+**MCP Tool Annotations (PR #512)**
+
+Added MCP tool annotations to all 20 tools following the [MCP specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations). These annotations help AI assistants understand tool behavior and capabilities.
+
+**Annotations added:**
+- `title`: Human-readable name for each tool
+- `readOnlyHint`: True for tools that don't modify state (11 tools)
+- `destructiveHint`: True for delete operations (3 tools)
+- `idempotentHint`: True for operations that produce same result when called repeatedly (14 tools)
+- `openWorldHint`: True for tools accessing external n8n API (13 tools)
+
+**Documentation tools** (7): All marked `readOnlyHint=true`, `idempotentHint=true`
+- `tools_documentation`, `search_nodes`, `get_node`, `validate_node`, `get_template`, `search_templates`, `validate_workflow`
+
+**Management tools** (13): All marked `openWorldHint=true`
+- Read-only: `n8n_get_workflow`, `n8n_list_workflows`, `n8n_validate_workflow`, `n8n_health_check`
+- Idempotent updates: `n8n_update_full_workflow`, `n8n_update_partial_workflow`, `n8n_autofix_workflow`
+- Destructive: `n8n_delete_workflow`, `n8n_executions` (delete action), `n8n_workflow_versions` (delete/truncate)
+
 ## [2.31.4] - 2026-01-02

 ### Fixed
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/n8n-mcp.svg)](https://www.npmjs.com/package/n8n-mcp)
 [![codecov](https://codecov.io/gh/czlonkowski/n8n-mcp/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/czlonkowski/n8n-mcp)
 [![Tests](https://img.shields.io/badge/tests-3336%20passing-brightgreen.svg)](https://github.com/czlonkowski/n8n-mcp/actions)
-[![n8n version](https://img.shields.io/badge/n8n-2.1.4-orange.svg)](https://github.com/n8n-io/n8n)
+[![n8n version](https://img.shields.io/badge/n8n-2.1.5-orange.svg)](https://github.com/n8n-io/n8n)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
 [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)

--- a/data/nodes.db
+++ b/data/nodes.db
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,24 +1,24 @@
 {
  "name": "n8n-mcp",
-  "version": "2.31.1",
+  "version": "2.31.5",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "n8n-mcp",
-      "version": "2.31.1",
+      "version": "2.31.5",
      "license": "MIT",
      "dependencies": {
        "@modelcontextprotocol/sdk": "1.20.1",
-        "@n8n/n8n-nodes-langchain": "^2.1.3",
+        "@n8n/n8n-nodes-langchain": "^2.1.4",
        "@supabase/supabase-js": "^2.57.4",
        "dotenv": "^16.5.0",
        "express": "^5.1.0",
        "express-rate-limit": "^7.1.5",
        "form-data": "^4.0.5",
        "lru-cache": "^11.2.1",
-        "n8n": "^2.1.4",
-        "n8n-core": "^2.1.3",
+        "n8n": "^2.1.5",
+        "n8n-core": "^2.1.4",
        "n8n-workflow": "^2.1.1",
        "openai": "^4.77.0",
        "sql.js": "^1.13.0",
@@ -7624,9 +7624,9 @@
      "license": "SEE LICENSE IN LICENSE.md"
    },
    "node_modules/@n8n/db": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/@n8n/db/-/db-1.1.3.tgz",
-      "integrity": "sha512-KQyHIHdKD6B1cJ7L0uk81i5vkiFQ6vVNIGRrnhCwkWi2gB9ySyu2TuvCQj7MOVVlb/EWLSDj96QfaWVUCXKaFw==",
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@n8n/db/-/db-1.1.4.tgz",
+      "integrity": "sha512-48wXccnSmyR1LcNU++7fiIvk7Th22bddDenLsehmPbnlwncnXW79UW7JarE5g1Hcu2IehbhIPgile7KYOBi4RQ==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@n8n/api-types": "1.1.1",
@@ -7640,7 +7640,7 @@
        "class-validator": "0.14.0",
        "flatted": "3.2.7",
        "lodash": "4.17.21",
-        "n8n-core": "2.1.3",
+        "n8n-core": "2.1.4",
        "n8n-workflow": "2.1.1",
        "nanoid": "3.3.8",
        "p-lazy": "3.1.0",
@@ -8158,9 +8158,9 @@
      }
    },
    "node_modules/@n8n/db/node_modules/n8n-core": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.3.tgz",
-      "integrity": "sha512-22WjdE0Yj2HUGI0pSWBB8oWeI8ceVz/ApD84AOE5aZU8ElDyTfmfk7pTZnYe3C4/4LHmuyiS+Ain6JpYlApEgQ==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.4.tgz",
+      "integrity": "sha512-n7PQIojUBDNU3o6IKz49ONAJpP2a6IqEr3S91D8/N9C89k7MGg3XXp8E52+vIc+zCKf91POhHvofZTxblmDC3g==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-s3": "3.808.0",
@@ -9522,9 +9522,9 @@
      }
    },
    "node_modules/@n8n/task-runner": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/@n8n/task-runner/-/task-runner-2.1.3.tgz",
-      "integrity": "sha512-DQANE5b0sT0XCuStfjidKV+CEbO+FQdFeZYqN1/TV49TDbcy08Pa/FUnRWpfHgNdBVco+pmq5xLdoY7hRm2tfw==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@n8n/task-runner/-/task-runner-2.1.4.tgz",
+      "integrity": "sha512-kWhPCDE5+H+DTHkEEWNSKu77wOcQvmF+mU06uEYIFWNYvUAycnUFXiW8K3pK89ePHNDXAaHGoFhuzihI6i77og==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@n8n/config": "2.0.2",
@@ -9535,7 +9535,7 @@
        "acorn-walk": "8.3.4",
        "lodash": "4.17.21",
        "luxon": "3.4.4",
-        "n8n-core": "2.1.3",
+        "n8n-core": "2.1.4",
        "n8n-workflow": "2.1.1",
        "nanoid": "3.3.8",
        "ws": "^8.18.0"
@@ -10055,9 +10055,9 @@
      }
    },
    "node_modules/@n8n/task-runner/node_modules/n8n-core": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.3.tgz",
-      "integrity": "sha512-22WjdE0Yj2HUGI0pSWBB8oWeI8ceVz/ApD84AOE5aZU8ElDyTfmfk7pTZnYe3C4/4LHmuyiS+Ain6JpYlApEgQ==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.4.tgz",
+      "integrity": "sha512-n7PQIojUBDNU3o6IKz49ONAJpP2a6IqEr3S91D8/N9C89k7MGg3XXp8E52+vIc+zCKf91POhHvofZTxblmDC3g==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-s3": "3.808.0",
@@ -23283,9 +23283,9 @@
      }
    },
    "node_modules/n8n": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/n8n/-/n8n-2.1.4.tgz",
-      "integrity": "sha512-mnGhIRIoaDnBIQd1ddDZBmfm9mVKNdhNPrgiYdzsSkG1QE6P4WI0ZUv3Z7Yus1tPK3QHtF4R0pGhzCOuifyfKA==",
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/n8n/-/n8n-2.1.5.tgz",
+      "integrity": "sha512-6yRks7uzRjPx3ZQXLQkfArwF78TzvkfTUvfwTTKRnGLk4Yuvmx+GXwByCyB3YIU7Szzi+80gnasmramKyRYldw==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-secrets-manager": "3.808.0",
@@ -23300,14 +23300,14 @@
        "@n8n/client-oauth2": "1.0.0-rc.0",
        "@n8n/config": "2.0.2",
        "@n8n/constants": "0.15.0",
-        "@n8n/db": "1.1.3",
+        "@n8n/db": "1.1.4",
        "@n8n/decorators": "1.1.1",
        "@n8n/di": "0.10.0",
        "@n8n/errors": "0.5.0",
        "@n8n/localtunnel": "3.0.0",
-        "@n8n/n8n-nodes-langchain": "2.1.3",
+        "@n8n/n8n-nodes-langchain": "2.1.4",
        "@n8n/permissions": "0.44.0",
-        "@n8n/task-runner": "2.1.3",
+        "@n8n/task-runner": "2.1.4",
        "@n8n/typeorm": "0.3.20-15",
        "@n8n/utils": "1.21.0",
        "@parcel/watcher": "^2.5.1",
@@ -23348,9 +23348,9 @@
        "lodash": "4.17.21",
        "luxon": "3.4.4",
        "mysql2": "3.15.0",
-        "n8n-core": "2.1.3",
+        "n8n-core": "2.1.4",
        "n8n-editor-ui": "2.1.2",
-        "n8n-nodes-base": "2.1.3",
+        "n8n-nodes-base": "2.1.4",
        "n8n-workflow": "2.1.1",
        "nanoid": "3.3.8",
        "nodemailer": "7.0.11",
@@ -24614,9 +24614,9 @@
      }
    },
    "node_modules/n8n/node_modules/@modelcontextprotocol/sdk/node_modules/zod-to-json-schema": {
-      "version": "3.25.0",
-      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.0.tgz",
-      "integrity": "sha512-HvWtU2UG41LALjajJrML6uQejQhNJx+JBO9IflpSja4R03iNWfKXrj6W2h7ljuLyc1nKS+9yDyL/9tD1U/yBnQ==",
+      "version": "3.25.1",
+      "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz",
+      "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==",
      "license": "ISC",
      "peerDependencies": {
        "zod": "^3.25 || ^4"
@@ -24634,9 +24634,9 @@
      }
    },
    "node_modules/n8n/node_modules/@n8n/n8n-nodes-langchain": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/@n8n/n8n-nodes-langchain/-/n8n-nodes-langchain-2.1.3.tgz",
-      "integrity": "sha512-XT4bAs0OBZiBqr9TQSzcIXDf4kXQkF5avHSgo2HStoPlK/en/eQmWmBbTimm4B2mA6HwggOM8LsYEJDADG8TFw==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@n8n/n8n-nodes-langchain/-/n8n-nodes-langchain-2.1.4.tgz",
+      "integrity": "sha512-6cFn7Zw3hUqvIF2lL/d+FFPFQHccIev5SE5d+P4n+d+l4Fal8EymnjvNy9+UKV9fsxJ4VK3RYtPr19bGu1CEng==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-sso-oidc": "3.808.0",
@@ -24698,7 +24698,7 @@
        "mammoth": "1.11.0",
        "mime-types": "3.0.1",
        "mongodb": "^6.17.0",
-        "n8n-nodes-base": "2.1.3",
+        "n8n-nodes-base": "2.1.4",
        "n8n-workflow": "2.1.1",
        "openai": "^6.9.0",
        "pdf-parse": "1.1.1",
@@ -25204,9 +25204,9 @@
      }
    },
    "node_modules/n8n/node_modules/@n8n/n8n-nodes-langchain/node_modules/@langchain/community/node_modules/zod": {
-      "version": "4.2.1",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.2.1.tgz",
-      "integrity": "sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw==",
+      "version": "4.3.4",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.4.tgz",
+      "integrity": "sha512-Zw/uYiiyF6pUT1qmKbZziChgNPRu+ZRneAsMUDU6IwmXdWt5JwcUfy2bvLOCUtz5UniaN/Zx5aFttZYbYc7O/A==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
@@ -26173,9 +26173,9 @@
      }
    },
    "node_modules/n8n/node_modules/langchain/node_modules/zod": {
-      "version": "4.2.1",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.2.1.tgz",
-      "integrity": "sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw==",
+      "version": "4.3.4",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.4.tgz",
+      "integrity": "sha512-Zw/uYiiyF6pUT1qmKbZziChgNPRu+ZRneAsMUDU6IwmXdWt5JwcUfy2bvLOCUtz5UniaN/Zx5aFttZYbYc7O/A==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
@@ -26215,9 +26215,9 @@
      }
    },
    "node_modules/n8n/node_modules/n8n-core": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.3.tgz",
-      "integrity": "sha512-22WjdE0Yj2HUGI0pSWBB8oWeI8ceVz/ApD84AOE5aZU8ElDyTfmfk7pTZnYe3C4/4LHmuyiS+Ain6JpYlApEgQ==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/n8n-core/-/n8n-core-2.1.4.tgz",
+      "integrity": "sha512-n7PQIojUBDNU3o6IKz49ONAJpP2a6IqEr3S91D8/N9C89k7MGg3XXp8E52+vIc+zCKf91POhHvofZTxblmDC3g==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-s3": "3.808.0",
@@ -26301,9 +26301,9 @@
      }
    },
    "node_modules/n8n/node_modules/n8n-nodes-base": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/n8n-nodes-base/-/n8n-nodes-base-2.1.3.tgz",
-      "integrity": "sha512-Ll34OuiZ5fl4MUCxNVb2X6dPxcH24Hx3Cfv/teagIjjI88XcVdPtNCbJfZjqrunOyzA3O5MECrDvm5EQD+qrbA==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/n8n-nodes-base/-/n8n-nodes-base-2.1.4.tgz",
+      "integrity": "sha512-6CW++gy0q7LgTM9UmxsNohlsBe6Q+QPEToiRYhqqLIvR8hn9wy2sr4cGsPWsflNAA28b8GKNj5+ueKZtq3Kd1w==",
      "license": "SEE LICENSE IN LICENSE.md",
      "dependencies": {
        "@aws-sdk/client-sso-oidc": "3.808.0",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "n8n-mcp",
-  "version": "2.31.4",
+  "version": "2.31.6",
  "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
@@ -141,15 +141,15 @@
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "1.20.1",
-    "@n8n/n8n-nodes-langchain": "^2.1.3",
+    "@n8n/n8n-nodes-langchain": "^2.1.4",
    "@supabase/supabase-js": "^2.57.4",
    "dotenv": "^16.5.0",
    "express": "^5.1.0",
    "express-rate-limit": "^7.1.5",
    "form-data": "^4.0.5",
    "lru-cache": "^11.2.1",
-    "n8n": "^2.1.4",
-    "n8n-core": "^2.1.3",
+    "n8n": "^2.1.5",
+    "n8n-core": "^2.1.4",
    "n8n-workflow": "^2.1.1",
    "openai": "^4.77.0",
    "sql.js": "^1.13.0",
--- a/src/mcp/tools-n8n-manager.ts
+++ b/src/mcp/tools-n8n-manager.ts
@@ -66,7 +66,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['name', 'nodes', 'connections']
-    }
+    },
+    annotations: {
+      title: 'Create Workflow',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_get_workflow',
@@ -86,7 +92,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['id']
-    }
+    },
+    annotations: {
+      title: 'Get Workflow',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_update_full_workflow',
@@ -120,7 +132,14 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['id']
-    }
+    },
+    annotations: {
+      title: 'Update Full Workflow',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_update_partial_workflow',
@@ -151,7 +170,14 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['id', 'operations']
-    }
+    },
+    annotations: {
+      title: 'Update Partial Workflow',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_delete_workflow',
@@ -165,7 +191,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['id']
-    }
+    },
+    annotations: {
+      title: 'Delete Workflow',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_list_workflows',
@@ -194,12 +226,18 @@ export const n8nManagementTools: ToolDefinition[] = [
          type: 'string', 
          description: 'Filter by project ID (enterprise feature)' 
        },
-        excludePinnedData: { 
-          type: 'boolean', 
-          description: 'Exclude pinned data from response (default: true)' 
+        excludePinnedData: {
+          type: 'boolean',
+          description: 'Exclude pinned data from response (default: true)'
        }
      }
-    }
+    },
+    annotations: {
+      title: 'List Workflows',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_validate_workflow',
@@ -227,16 +265,22 @@ export const n8nManagementTools: ToolDefinition[] = [
              type: 'boolean', 
              description: 'Validate n8n expressions (default: true)' 
            },
-            profile: { 
-              type: 'string', 
+            profile: {
+              type: 'string',
              enum: ['minimal', 'runtime', 'ai-friendly', 'strict'],
-              description: 'Validation profile to use (default: runtime)' 
+              description: 'Validation profile to use (default: runtime)'
            }
          }
        }
      },
      required: ['id']
-    }
+    },
+    annotations: {
+      title: 'Validate Workflow',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_autofix_workflow',
@@ -271,7 +315,14 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['id']
-    }
+    },
+    annotations: {
+      title: 'Autofix Workflow',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },

  // Execution Management Tools
@@ -328,7 +379,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['workflowId']
-    }
+    },
+    annotations: {
+      title: 'Test Workflow',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_executions',
@@ -410,7 +467,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['action']
-    }
+    },
+    annotations: {
+      title: 'Manage Executions',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true,
+    },
  },

  // System Tools
@@ -431,7 +494,13 @@ export const n8nManagementTools: ToolDefinition[] = [
          description: 'Include extra details in diagnostic mode (default: false)'
        }
      }
-    }
+    },
+    annotations: {
+      title: 'Health Check',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
  },
  {
    name: 'n8n_workflow_versions',
@@ -485,7 +554,13 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['mode']
-    }
+    },
+    annotations: {
+      title: 'Workflow Versions',
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: true,
+    },
  },

  // Template Deployment Tool
@@ -520,6 +595,12 @@ export const n8nManagementTools: ToolDefinition[] = [
        }
      },
      required: ['templateId']
-    }
+    },
+    annotations: {
+      title: 'Deploy Template',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
  }
-];
+];
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -25,6 +25,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
        },
      },
    },
+    annotations: {
+      title: 'Tools Documentation',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'search_nodes',
@@ -55,6 +60,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
      },
      required: ['query'],
    },
+    annotations: {
+      title: 'Search Nodes',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'get_node',
@@ -108,6 +118,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
      },
      required: ['nodeType'],
    },
+    annotations: {
+      title: 'Get Node Info',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'validate_node',
@@ -188,6 +203,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
      },
      required: ['nodeType', 'displayName', 'valid']
    },
+    annotations: {
+      title: 'Validate Node Config',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'get_template',
@@ -208,6 +228,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
      },
      required: ['templateId'],
    },
+    annotations: {
+      title: 'Get Template',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'search_templates',
@@ -303,6 +328,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
        },
      },
    },
+    annotations: {
+      title: 'Search Templates',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
  {
    name: 'validate_workflow',
@@ -388,6 +418,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
      },
      required: ['valid', 'summary']
    },
+    annotations: {
+      title: 'Validate Workflow',
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
  },
 ];

--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -10,6 +10,23 @@ export interface MCPServerConfig {
  authToken?: string;
 }

+/**
+ * MCP Tool annotations to help AI assistants understand tool behavior.
+ * Per MCP spec: https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations
+ */
+export interface ToolAnnotations {
+  /** Human-readable title for the tool */
+  title?: string;
+  /** If true, the tool does not modify its environment */
+  readOnlyHint?: boolean;
+  /** If true, the tool may perform destructive updates to its environment */
+  destructiveHint?: boolean;
+  /** If true, calling the tool repeatedly with the same arguments has no additional effect */
+  idempotentHint?: boolean;
+  /** If true, the tool may interact with external entities (APIs, services) */
+  openWorldHint?: boolean;
+}
+
 export interface ToolDefinition {
  name: string;
  description: string;
@@ -25,6 +42,8 @@ export interface ToolDefinition {
    required?: string[];
    additionalProperties?: boolean | Record<string, any>;
  };
+  /** Tool behavior hints for AI assistants */
+  annotations?: ToolAnnotations;
 }

 export interface ResourceDefinition {