fix: trim patterns response tokens and add missing documentation (#683)

- Trim task-specific patterns ~64%: drop displayName, shorten field names
  (frequency→freq), cap chains at 5, use short node type names in chains
- Add patterns mode to tools_documentation essentials, full docs, and
  tools-documentation.ts overview (was completely missing)
- Document includeOperations omission behavior for trigger/freeform nodes
- Add patterns return shape to search_templates returns documentation
- Trim search_nodes examples from 11 to 6

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/mcp/tool-docs/discovery/search-nodes.ts

@@ -26,21 +26,16 @@ export const searchNodesDoc: ToolDocumentation = {
       mode: { type: 'string', description: 'Search mode: "OR" (any word matches, default), "AND" (all words required), "FUZZY" (typo-tolerant)', required: false },
       source: { type: 'string', description: 'Filter by node source: "all" (default, everything), "core" (n8n base nodes only), "community" (community nodes only), "verified" (verified community nodes only)', required: false },
       includeExamples: { type: 'boolean', description: 'Include top 2 real-world configuration examples from popular templates for each node. Default: false. Adds ~200-400 tokens per node.', required: false },
-      includeOperations: { type: 'boolean', description: 'Include resource/operation tree per node. Default: false. Adds ~100-300 tokens per result but saves a get_node round-trip.', required: false }
+      includeOperations: { type: 'boolean', description: 'Include resource/operation tree per node. Default: false. Adds ~100-300 tokens per result but saves a get_node round-trip. Only returned for nodes with resource/operation patterns — trigger nodes and freeform nodes (Code, HTTP Request) omit this field.', required: false }
     },
     returns: 'Array of node objects sorted by relevance score. Each object contains: nodeType, displayName, description, category, relevance score. For community nodes, also includes: isCommunity (boolean), isVerified (boolean), authorName (string), npmDownloads (number). Common nodes appear first when relevance is similar.',
     examples: [
       'search_nodes({query: "webhook"}) - Returns Webhook node as top result',
-      'search_nodes({query: "database"}) - Returns MySQL, Postgres, MongoDB, Redis, etc.',
       'search_nodes({query: "google sheets", mode: "AND"}) - Requires both words',
       'search_nodes({query: "slak", mode: "FUZZY"}) - Finds Slack despite typo',
-      'search_nodes({query: "http api"}) - Finds HTTP Request, GraphQL, REST nodes',
-      'search_nodes({query: "transform data"}) - Finds Set, Code, Function, Item Lists nodes',
       'search_nodes({query: "scraping", source: "community"}) - Find community scraping nodes',
-      'search_nodes({query: "pdf", source: "verified"}) - Find verified community PDF nodes',
-      'search_nodes({query: "brightdata"}) - Find BrightData community node',
       'search_nodes({query: "slack", includeExamples: true}) - Get Slack with template examples',
-      'search_nodes({query: "slack", includeOperations: true}) - Get Slack with resource/operation tree'
+      'search_nodes({query: "slack", includeOperations: true}) - Get Slack with resource/operation tree (7 resources, 44 ops)'
     ],
     useCases: [
       'Finding nodes when you know partial names',

src/mcp/tool-docs/templates/search-templates.ts

@@ -4,7 +4,7 @@ export const searchTemplatesDoc: ToolDocumentation = {
   name: 'search_templates',
   category: 'templates',
   essentials: {
-    description: 'Unified template search with multiple modes: keyword search, by node types, by task type, or by metadata. 2,700+ templates available.',
+    description: 'Unified template search with multiple modes: keyword search, by node types, by task type, by metadata, or patterns. 2,700+ templates available.',
     keyParameters: ['searchMode', 'query', 'nodeTypes', 'task', 'limit'],
     example: 'search_templates({searchMode: "by_task", task: "webhook_processing"})',
     performance: 'Fast (<100ms) - FTS5 full-text search',
@@ -12,7 +12,9 @@ export const searchTemplatesDoc: ToolDocumentation = {
       'searchMode="keyword" (default): Search by name/description',
       'searchMode="by_nodes": Find templates using specific nodes',
       'searchMode="by_task": Get curated templates for common tasks',
-      'searchMode="by_metadata": Filter by complexity, services, audience'
+      'searchMode="by_metadata": Filter by complexity, services, audience',
+      'searchMode="patterns": Workflow pattern summaries across 10 task categories',
+      'patterns without task: overview of all categories. patterns with task: node frequencies + connection chains'
     ]
   },
   full: {
@@ -21,14 +23,15 @@ export const searchTemplatesDoc: ToolDocumentation = {
 - by_nodes: Find templates that use specific node types
 - by_task: Get curated templates for predefined task categories
 - by_metadata: Filter by complexity, setup time, required services, or target audience
+- patterns: Lightweight workflow pattern summaries mined from 2,700+ templates
 
-**Available Task Types (for searchMode="by_task"):**
+**Available Task Types (for searchMode="by_task" and "patterns"):**
 ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations`,
     parameters: {
       searchMode: {
         type: 'string',
         required: false,
-        description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata"'
+        description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata", "patterns"'
       },
       query: {
         type: 'string',
@@ -43,7 +46,7 @@ ai_automation, data_sync, webhook_processing, email_automation, slack_integratio
       task: {
         type: 'string',
         required: false,
-        description: 'For searchMode=by_task: Task type (ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations)'
+        description: 'For searchMode=by_task: Task type. For searchMode=patterns: optional category filter (omit for overview of all categories). Values: ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations'
       },
       complexity: {
         type: 'string',
@@ -91,38 +94,45 @@ ai_automation, data_sync, webhook_processing, email_automation, slack_integratio
         description: 'Pagination offset (default 0)'
       }
     },
-    returns: `Returns an object containing:
+    returns: `For keyword/by_nodes/by_task/by_metadata modes:
 - templates: Array of matching templates
   - id: Template ID for get_template()
-  - name: Template name
-  - description: What the workflow does
-  - author: Creator information
-  - nodes: Array of node types used
-  - views: Popularity metric
-  - created: Creation date
-  - url: Link to template
-  - metadata: AI-generated metadata (complexity, services, etc.)
+  - name, description, author, nodes, views, created, url, metadata
 - totalFound: Total matching templates
-- searchMode: The mode used`,
+- searchMode: The mode used
+
+For patterns mode (no task):
+- templateCount, generatedAt
+- categories: Array of {category, templateCount, pattern, topNodes}
+- tip: How to drill into a specific category
+
+For patterns mode (with task):
+- category, templateCount, pattern
+- nodes: Array of {type, freq, role} (top nodes by frequency, limited by 'limit')
+- chains: Array of {path, count, freq} (top 5 connection chains, short node names)`,
     examples: [
       '// Keyword search (default)\nsearch_templates({query: "chatbot"})',
       '// Find templates using specific nodes\nsearch_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})',
       '// Get templates for a task type\nsearch_templates({searchMode: "by_task", task: "webhook_processing"})',
       '// Filter by metadata\nsearch_templates({searchMode: "by_metadata", complexity: "simple", requiredService: "openai"})',
-      '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})'
+      '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})',
+      '// Pattern overview — all categories with top nodes (~550 tokens)\nsearch_templates({searchMode: "patterns"})',
+      '// Detailed patterns for a category — node frequencies + connection chains\nsearch_templates({searchMode: "patterns", task: "ai_automation"})'
     ],
     useCases: [
       'Find workflows by business purpose (keyword search)',
       'Find templates using specific integrations (by_nodes)',
       'Get pre-built solutions for common tasks (by_task)',
       'Filter by complexity for team skill level (by_metadata)',
-      'Find templates requiring specific services (by_metadata)'
+      'Understand common workflow shapes before building (patterns)',
+      'Architecture planning — which nodes go together (patterns)'
     ],
     performance: `Fast performance across all modes:
 - keyword: <50ms with FTS5 indexing
 - by_nodes: <100ms with indexed lookups
 - by_task: <50ms from curated cache
-- by_metadata: <100ms with filtered queries`,
+- by_metadata: <100ms with filtered queries
+- patterns: <10ms (pre-mined, cached in memory)`,
     bestPractices: [
       'Use searchMode="by_task" for common automation patterns',
       'Use searchMode="by_nodes" when you know which integrations you need',