feat: improve MCP tool descriptions and add workflow guide tool

- Added new 'start_here_workflow_guide' tool for AI agents to get started
- Clarified search_nodes behavior (OR logic for multiple words)
- Simplified list_nodes description with package name clarification
- Updated get_node_info to recommend essentials first
- Made get_property_dependencies description more concise with example
- Removed confusing quick reference comment (now in dedicated tool)

The workflow guide tool provides:
- Recommended workflow patterns
- Search tips and best practices
- Common node references
- Known issues and workarounds
- Performance guidance

🤖 Generated with Claude Code

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

src/mcp/server-update.ts

@@ -140,6 +140,8 @@ export class N8NDocumentationMCPServer {
 
   async executeTool(name: string, args: any): Promise<any> {
     switch (name) {
+      case 'start_here_workflow_guide':
+        return this.getWorkflowGuide(args.topic);
       case 'list_nodes':
         return this.listNodes(args);
       case 'get_node_info':
@@ -767,6 +769,134 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
     };
   }
 
+  private async getWorkflowGuide(topic?: string): Promise<any> {
+    const guides: Record<string, any> = {
+      overview: {
+        title: "n8n MCP Tools Quick Start Guide",
+        sections: {
+          recommended_workflow: {
+            title: "Recommended Workflow",
+            steps: [
+              "1. search_nodes({query:'slack'}) - Find nodes by keyword",
+              "2. get_node_essentials('nodes-base.slack') - Get only essential properties (<5KB)",
+              "3. get_node_for_task('send_slack_message') - Get pre-configured settings",
+              "4. validate_node_config() - Validate before use"
+            ],
+            tip: "Avoid get_node_info unless you need ALL properties (100KB+ response)"
+          },
+          essential_tools: {
+            discovery: "list_nodes({category:'trigger'}) - Browse by category",
+            quick_config: "get_node_essentials() - 95% smaller than get_node_info",
+            tasks: "list_tasks() then get_node_for_task() - Pre-configured common tasks",
+            validation: "validate_node_config() - Catch errors before execution"
+          }
+        }
+      },
+      workflow: {
+        title: "Efficient Workflow Patterns",
+        patterns: [
+          {
+            name: "Building from scratch",
+            steps: [
+              "search_nodes or list_nodes to find nodes",
+              "get_node_essentials for configuration",
+              "validate_node_config before execution"
+            ]
+          },
+          {
+            name: "Common tasks",
+            steps: [
+              "list_tasks() to see available templates",
+              "get_node_for_task() for instant configuration",
+              "Fill in userMustProvide fields"
+            ]
+          }
+        ]
+      },
+      search_tips: {
+        title: "Search Best Practices",
+        tips: [
+          "search_nodes returns ANY word match (OR logic)",
+          "'send slack message' finds nodes with 'send' OR 'slack' OR 'message'",
+          "Single words are more precise: 'slack' vs 'slack message'",
+          "Use list_nodes({category:'trigger'}) if search fails",
+          "Node types need prefix: 'nodes-base.slack' not just 'slack'"
+        ]
+      },
+      common_nodes: {
+        title: "Most Used Nodes",
+        categories: {
+          triggers: ["webhook", "schedule", "emailReadImap", "slackTrigger"],
+          core: ["httpRequest", "code", "set", "if", "merge", "splitInBatches"],
+          integrations: ["slack", "gmail", "googleSheets", "postgres", "mongodb"],
+          ai: ["agent", "openAi", "chainLlm", "documentLoader"]
+        }
+      },
+      known_issues: {
+        title: "Known Issues & Workarounds",
+        issues: [
+          "Package names: Use 'n8n-nodes-base' NOT '@n8n/n8n-nodes-base'",
+          "Duplicate properties: Check showWhen/hideWhen conditions",
+          "Large responses: Use get_node_essentials instead of get_node_info",
+          "Property search: Some nodes have 200+ properties, use search_node_properties",
+          "Node not found: Try without prefix or lowercase"
+        ]
+      },
+      performance: {
+        title: "Performance Guide",
+        tools: {
+          fast: [
+            "get_node_essentials - <5KB responses",
+            "search_nodes - Indexed search",
+            "list_nodes - Direct queries",
+            "start_here_workflow_guide - Static content"
+          ],
+          slow: [
+            "get_node_info - 100KB+ responses",
+            "get_node_documentation - Can be large"
+          ]
+        },
+        tips: [
+          "Use get_node_essentials for 95% of use cases",
+          "Only use get_node_info when essentials lack needed property",
+          "Results are cached for repeated queries"
+        ]
+      }
+    };
+
+    if (topic && guides[topic]) {
+      return guides[topic];
+    }
+
+    // Return complete overview
+    return {
+      title: "n8n MCP Tools Complete Guide",
+      quickStart: guides.overview,
+      sections: {
+        workflow: guides.workflow,
+        searchTips: guides.search_tips,
+        commonNodes: guides.common_nodes,
+        knownIssues: guides.known_issues,
+        performance: guides.performance
+      },
+      examples: {
+        "Find and configure Slack": [
+          "search_nodes({query:'slack'})",
+          "get_node_essentials('nodes-base.slack')",
+          "get_node_for_task('send_slack_message')"
+        ],
+        "Set up webhook trigger": [
+          "get_node_for_task('receive_webhook')",
+          "// Returns pre-configured webhook with instructions"
+        ],
+        "HTTP API call": [
+          "get_node_essentials('nodes-base.httpRequest')",
+          "search_node_properties('nodes-base.httpRequest', 'auth')"
+        ]
+      }
+    };
+  }
+
   // Add connect method to accept any transport
   async connect(transport: any): Promise<void> {
     await this.ensureInitialized();

src/mcp/tools-update.ts

@@ -7,9 +7,23 @@ import { ToolDefinition } from '../types';
  * Designed to help AI agents avoid common pitfalls and build workflows efficiently.
  */
 export const n8nDocumentationToolsFinal: ToolDefinition[] = [
+  {
+    name: 'start_here_workflow_guide',
+    description: `START HERE! Essential guide for using n8n MCP tools effectively. Returns workflow recommendations, common patterns, performance tips, and known issues. Call this FIRST before using other tools to avoid common mistakes and work efficiently.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        topic: {
+          type: 'string',
+          enum: ['overview', 'workflow', 'search_tips', 'common_nodes', 'known_issues', 'performance'],
+          description: 'Optional: Get specific guidance on a topic. Default returns complete overview.',
+        },
+      },
+    },
+  },
   {
     name: 'list_nodes',
-    description: `Browse n8n's 525+ nodes by category/type/package. BEST FOR: Initial discovery, browsing categories, finding all nodes of a type. Returns lightweight list with names/descriptions only. Common patterns: list_nodes({category:"trigger"}) for workflow starters, list_nodes({package:"n8n-nodes-base", limit:200}) to see all integrations. Categories: "trigger" (104), "transform" (data processing), "output" (destinations), "input" (data sources). TIP: More reliable than search_nodes for discovery. Use limit:200+ to see all nodes in large categories.`,
+    description: `List n8n nodes with optional filters. Common usage: list_nodes({limit:200}) for all nodes, list_nodes({category:'trigger'}) for triggers. Note: Use exact package names - 'n8n-nodes-base' not '@n8n/n8n-nodes-base'. Categories: "trigger" (104 nodes), "transform", "output", "input". Returns node names and descriptions.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -40,7 +54,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'get_node_info',
-    description: `Get COMPLETE technical schema for a node. WARNING: Returns massive JSON (often 100KB+) with all properties, operations, credentials. Contains duplicates and complex conditional logic. TIPS: 1) Try get_node_documentation first, 2) Look for "required":true properties, 3) Find properties without "displayOptions" for simpler versions, 4) Check "default" values. Node type MUST include prefix: "nodes-base.httpRequest" NOT "httpRequest". If not found, try lowercase or without prefix.`,
+    description: `Get COMPLETE technical schema for a node. WARNING: Returns massive JSON (often 100KB+) with all properties, operations, credentials. Contains duplicates and complex conditional logic. TIPS: 1) Use get_node_essentials first for common use cases, 2) Try get_node_documentation for human-readable info, 3) Look for "required":true properties, 4) Find properties without "displayOptions" for simpler versions. Node type MUST include prefix: "nodes-base.httpRequest" NOT "httpRequest".`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -54,7 +68,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'search_nodes',
-    description: `Find nodes by keyword. CRITICAL: Use SINGLE WORDS only! Multi-word searches usually fail. The search is substring-based (not semantic). Examples - WORKS: "slack", "email", "sheet", "webhook". FAILS: "send message", "google sheets", "http request". If no results: 1) Try shorter word, 2) Try related terms, 3) Use list_nodes instead. Searches in node names, descriptions, and docs. Returns max 20 by default with relevance scoring.`,
+    description: `Search nodes by keywords. Returns nodes containing ANY of the search words (OR logic). Examples: 'slack' finds Slack node, 'send message' finds any node with 'send' OR 'message'. Best practice: Use single words for precise results, multiple words for broader search. Searches in node names and descriptions. If no results, try shorter words or use list_nodes by category.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -185,7 +199,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
   },
   {
     name: 'get_property_dependencies',
-    description: `Analyze property dependencies and visibility conditions for a node. Shows which properties control the visibility of others, helping you understand the configuration flow. Optionally provide a partial config to see what would be visible/hidden with those settings.`,
+    description: `Shows which properties control the visibility of other properties. Helps understand why certain fields appear/disappear based on configuration. Example: In HTTP Request, 'sendBody=true' reveals body-related properties. Optionally provide a config to see what would be visible/hidden with those settings.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -206,12 +220,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
 /**
  * QUICK REFERENCE for AI Agents:
  * 
- * 1. DISCOVERY FLOW:
- *    - Start: get_database_statistics() - see what's available
- *    - Browse: list_nodes({category:"trigger"}) - find workflow starters  
- *    - Search: search_nodes({query:"slack"}) - SINGLE WORDS ONLY
- *    - Learn: get_node_documentation("nodes-base.slack") - understand usage
- *    - Configure: get_node_info("nodes-base.slack") - get all properties
+ * 1. RECOMMENDED WORKFLOW:
+ *    - Start: search_nodes → get_node_essentials → get_node_for_task → validate_node_config
+ *    - Discovery: list_nodes({category:"trigger"}) for browsing categories
+ *    - Quick Config: get_node_essentials("nodes-base.httpRequest") - only essential properties
+ *    - Full Details: get_node_info only when essentials aren't enough
  * 
  * 2. COMMON NODE TYPES:
  *    Triggers: webhook, schedule, emailReadImap, slackTrigger
@@ -220,13 +233,17 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
  *    AI: agent, openAi, chainLlm, documentLoader
  * 
  * 3. SEARCH TIPS:
- *    - Always use single words
- *    - Try: service name, action verb, data type
- *    - If fails: use list_nodes with category
+ *    - search_nodes returns ANY word match (OR logic)
+ *    - Single words more precise, multiple words broader
+ *    - If no results: use list_nodes with category filter
  * 
- * 4. PROPERTY TIPS:
- *    - Look for "required": true first
- *    - Ignore complex "displayOptions" initially
- *    - Use "default" values as guidance
- *    - Simpler properties have no displayOptions
+ * 4. KNOWN ISSUES:
+ *    - Some nodes have duplicate properties with different conditions
+ *    - Package names: use 'n8n-nodes-base' not '@n8n/n8n-nodes-base'
+ *    - Check showWhen/hideWhen to identify the right property variant
+ * 
+ * 5. PERFORMANCE:
+ *    - get_node_essentials: Fast (<5KB)
+ *    - get_node_info: Slow (100KB+) - use sparingly
+ *    - search_nodes/list_nodes: Fast, cached
  */