refactor: rewrite all MCP tool documentation for AI agent optimization

- Redesigned documentation to be utilitarian and AI-agent focused
- Removed all pleasantries, emojis, and conversational language
- Added concrete numbers throughout (528 nodes, 108 triggers, 264 AI tools)
- Updated all tool descriptions with practical, actionable information
- Enhanced examples with actual return structures and usage patterns
- Made Code node guides prominently featured in overview
- Verified documentation accuracy through extensive testing
- Standardized format across all 30+ tool documentation files

Documentation now optimized for token efficiency while maintaining
clarity and completeness for AI agent consumption.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts

@@ -24,8 +24,53 @@ export const n8nCreateWorkflowDoc: ToolDocumentation = {
     },
     returns: 'Created workflow object with id, name, nodes, connections, active status',
     examples: [
-      'n8n_create_workflow({name: "Webhook to Slack", nodes: [...], connections: {...}}) - Basic workflow',
-      'n8n_create_workflow({name: "Data ETL", nodes: [...], connections: {...], settings: {timezone: "UTC"}}) - With settings'
+      `// Basic webhook to Slack workflow
+n8n_create_workflow({
+  name: "Webhook to Slack",
+  nodes: [
+    {
+      id: "webhook_1",
+      name: "Webhook",
+      type: "n8n-nodes-base.webhook",
+      typeVersion: 1,
+      position: [250, 300],
+      parameters: {
+        httpMethod: "POST",
+        path: "slack-notify"
+      }
+    },
+    {
+      id: "slack_1",
+      name: "Slack",
+      type: "n8n-nodes-base.slack",
+      typeVersion: 1,
+      position: [450, 300],
+      parameters: {
+        resource: "message",
+        operation: "post",
+        channel: "#general",
+        text: "={{$json.message}}"
+      }
+    }
+  ],
+  connections: {
+    "webhook_1": {
+      "main": [[{node: "slack_1", type: "main", index: 0}]]
+    }
+  }
+})`,
+      `// Workflow with settings and error handling
+n8n_create_workflow({
+  name: "Data Processing",
+  nodes: [...],
+  connections: {...},
+  settings: {
+    timezone: "America/New_York",
+    errorWorkflow: "error_handler_workflow_id",
+    saveDataSuccessExecution: "all",
+    saveDataErrorExecution: "all"
+  }
+})`
     ],
     useCases: [
       'Deploy validated workflows',
@@ -41,10 +86,11 @@ export const n8nCreateWorkflowDoc: ToolDocumentation = {
       'Test with n8n_trigger_webhook_workflow'
     ],
     pitfalls: [
-      'Requires API configuration',
-      'Created workflows are inactive',
-      'Node IDs must be unique',
-      'Credentials configured separately'
+      '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - tool unavailable without n8n API access',
+      'Workflows created in INACTIVE state - must activate separately',
+      'Node IDs must be unique within workflow',
+      'Credentials must be configured separately in n8n',
+      'Node type names must include package prefix (e.g., "n8n-nodes-base.slack")'
     ],
     relatedTools: ['validate_workflow', 'n8n_update_partial_workflow', 'n8n_trigger_webhook_workflow']
   }

src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts

@@ -15,21 +15,43 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
     ]
   },
   full: {
-    description: 'Updates workflows using surgical diff operations instead of full replacement. Supports 13 operation types for precise modifications. Operations are validated and applied atomically - all succeed or none are applied. Maximum 5 operations per call for safety.',
+    description: `Updates workflows using surgical diff operations instead of full replacement. Supports 13 operation types for precise modifications. Operations are validated and applied atomically - all succeed or none are applied. Maximum 5 operations per call for safety.
+
+## Available Operations:
+
+### Node Operations (6 types):
+- **addNode**: Add a new node with name, type, and position (required)
+- **removeNode**: Remove a node by ID or name
+- **updateNode**: Update node properties using dot notation (e.g., 'parameters.url')
+- **moveNode**: Change node position [x, y]
+- **enableNode**: Enable a disabled node
+- **disableNode**: Disable an active node
+
+### Connection Operations (3 types):
+- **addConnection**: Connect nodes (source→target)
+- **removeConnection**: Remove connection between nodes
+- **updateConnection**: Modify connection properties
+
+### Metadata Operations (4 types):
+- **updateSettings**: Modify workflow settings
+- **updateName**: Rename the workflow
+- **addTag**: Add a workflow tag
+- **removeTag**: Remove a workflow tag`,
     parameters: {
       id: { type: 'string', required: true, description: 'Workflow ID to update' },
       operations: { 
         type: 'array', 
         required: true, 
-        description: 'Array of diff operations. Each must have "type" field and operation-specific properties. Max 5 operations.' 
+        description: 'Array of diff operations. Each must have "type" field and operation-specific properties. Max 5 operations. Nodes can be referenced by ID or name.' 
       },
       validateOnly: { type: 'boolean', description: 'If true, only validate operations without applying them' }
     },
     returns: 'Updated workflow object or validation results if validateOnly=true',
     examples: [
-      'n8n_update_partial_workflow({id: "abc", operations: [{type: "updateNode", nodeId: "n1", updates: {name: "New Name"}}]})',
-      'n8n_update_partial_workflow({id: "xyz", operations: [{type: "addConnection", source: "n1", target: "n2"}]})',
-      'n8n_update_partial_workflow({id: "123", operations: [{type: "removeNode", nodeId: "oldNode"}], validateOnly: true})'
+      '// Update node parameter\nn8n_update_partial_workflow({id: "abc", operations: [{type: "updateNode", nodeName: "HTTP Request", changes: {"parameters.url": "https://api.example.com"}}]})',
+      '// Add connection between nodes\nn8n_update_partial_workflow({id: "xyz", operations: [{type: "addConnection", source: "Webhook", target: "Slack", sourceOutput: "main", targetInput: "main"}]})',
+      '// Multiple operations in one call\nn8n_update_partial_workflow({id: "123", operations: [\n  {type: "addNode", node: {name: "Transform", type: "n8n-nodes-base.code", position: [400, 300]}},\n  {type: "addConnection", source: "Webhook", target: "Transform"},\n  {type: "updateSettings", settings: {timezone: "America/New_York"}}\n]})',
+      '// Validate before applying\nn8n_update_partial_workflow({id: "456", operations: [{type: "removeNode", nodeName: "Old Process"}], validateOnly: true})'
     ],
     useCases: [
       'Update single node parameters',
@@ -46,11 +68,12 @@ export const n8nUpdatePartialWorkflowDoc: ToolDocumentation = {
       'Check operation order for dependencies'
     ],
     pitfalls: [
-      'Requires N8N_API_URL and N8N_API_KEY configured',
-      'Maximum 5 operations per call',
-      'Operations must be valid together',
-      'Some operations have dependencies',
-      'See full docs for operation schemas'
+      '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - will not work without n8n API access',
+      'Maximum 5 operations per call - split larger updates',
+      'Operations validated together - all must be valid',
+      'Order matters for dependent operations (e.g., must add node before connecting to it)',
+      'Node references accept ID or name, but name must be unique',
+      'Dot notation for nested updates: use "parameters.url" not nested objects'
     ],
     relatedTools: ['n8n_update_full_workflow', 'n8n_get_workflow', 'validate_workflow', 'tools_documentation']
   }