fix: default n8n_executions action and n8n_workflow_versions mode to list, alias retired get_node vocabulary (#1051)

Telemetry for the last week showed roughly 1,800 error_occurred events from
three call shapes that carried enough information to act on.

n8n_executions: action is optional and defaults to list; get without id lists
the executions of the given workflow (or recent executions) and says so in the
response message; delete stays strict; unknown actions get a hint when the
value belongs to another tool or is a common spelling of list. The dispatch
normalises action through resolveRequestedOperation, the same function the
DISABLED_TOOL_OPERATIONS gate uses, and the fallback refuses to list when list
is disabled.

n8n_workflow_versions: mode defaults to list in the JSON schema, the Zod
schema and the policy default map; required: ['mode'] is dropped. It and
n8n_test_workflow accept id as an alias for workflowId (blank workflowId
counts as absent, numeric id is accepted); the n8n_test_workflow
missing-parameter error names the parameter and the alias.

get_node: retired get_node_essentials / get_node_info vocabulary is mapped
onto mode + detail before validation and logged at debug level. Schemas and
docs keep advertising only the canonical values.

A filtered tool schema now drops a default that names a disabled operation.

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

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MnKJXcGCxs2Q4P31koUzsP

Author: czlonkowski

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.79.0] - 2026-09-02
+
+### Changed
+
+- **The most common agent call errors now resolve instead of failing** ([#1051](https://github.com/czlonkowski/n8n-mcp/issues/1051)). Telemetry for the last week showed roughly 1,800 `error_occurred` events from three call shapes that carried enough information to act on. `n8n_executions` no longer requires `action`: an omitted value lists executions, and `action=get` without an `id` lists the executions of the given workflow (or recent executions) and says so in the response `message`; `delete` still requires `id`, and an unknown action gets a suggestion when the value belongs to another tool or is a common misspelling of `list`. `n8n_workflow_versions` defaults `mode` to `list`. `n8n_workflow_versions` and `n8n_test_workflow` accept `id` as an alias for `workflowId`, and the missing-parameter error of `n8n_test_workflow` names the parameter and the alias. `get_node` maps the retired `get_node_essentials` / `get_node_info` vocabulary onto the canonical parameters before validation: `mode` values `essentials`, `minimal`, `standard`, `full` and `operations` become `mode=info` at the matching `detail`, `properties` and `search` become `search_properties`, and `detail` values `essentials`, `summary` and `short` become `standard`, `minimal` and `minimal`. Aliases are logged at debug level; the schemas and documentation advertise only the canonical values. The `DISABLED_TOOL_OPERATIONS` policy treats an omitted `action` or `mode` as the new default, so a rule that disables `list` still applies, the `get`-without-`id` fallback refuses to list when `list` is disabled, and a filtered tool schema drops a `default` that names a disabled operation. Callers that already pass the canonical parameters see no change.
+
 ## [2.78.0] - 2026-09-02
 
 ### Added

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.78.0",
+  "version": "2.79.0",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.78.0",
+  "version": "2.79.0",
   "description": "n8n MCP Server Runtime Dependencies Only",
   "private": true,
   "dependencies": {

package.runtime.json

@@ -608,7 +608,7 @@ const cancelTestRunSchema = z.object({
 const versionIdValue = z.union([z.number().int(), z.string().min(1)]);
 
 const workflowVersionsSchema = z.object({
-  mode: z.enum(['list', 'get', 'rollback', 'delete', 'prune', 'diff']),
+  mode: z.preprocess(emptyToUndefined, z.enum(['list', 'get', 'rollback', 'delete', 'prune', 'diff']).default('list')),
   source: z.enum(['local', 'native']).optional(),
   workflowId: z.string().optional(),
   versionId: versionIdValue.optional(),

src/mcp/handlers-n8n-manager.ts

@@ -0,0 +1,119 @@
+/**
+ * Aliases for parameter vocabulary that agents keep sending after a tool was
+ * renamed or consolidated. Each map is applied before validation so a caller
+ * using the old spelling gets the canonical behaviour instead of an error.
+ * The tool schemas and documentation advertise only the canonical values.
+ */
+
+import { logger } from '../utils/logger';
+
+/**
+ * `get_node` grew out of `get_node_essentials` / `get_node_info`, and prompts
+ * written against those tools still send their vocabulary as `mode` or
+ * `detail`. Retired values map onto the canonical `mode` + `detail` pair.
+ */
+const GET_NODE_MODE_ALIASES: Record<string, { mode: string; detail?: string }> = {
+  essentials: { mode: 'info', detail: 'standard' },
+  minimal: { mode: 'info', detail: 'minimal' },
+  standard: { mode: 'info', detail: 'standard' },
+  full: { mode: 'info', detail: 'full' },
+  operations: { mode: 'info', detail: 'standard' },
+  properties: { mode: 'search_properties' },
+  search: { mode: 'search_properties' },
+};
+
+const GET_NODE_DETAIL_ALIASES: Record<string, string> = {
+  essentials: 'standard',
+  summary: 'minimal',
+  short: 'minimal',
+};
+
+export interface GetNodeParams {
+  mode?: string;
+  detail?: string;
+}
+
+/**
+ * Resolves retired `mode` / `detail` spellings for `get_node` to canonical
+ * values. Unknown and non-string values pass through unchanged so the
+ * existing validation still names them in its error. Undefined stays
+ * undefined so the handler's own defaults apply.
+ */
+export function resolveGetNodeAliases(mode?: unknown, detail?: unknown): GetNodeParams {
+  const aliased: string[] = [];
+  let resolvedMode = mode as string | undefined;
+  let resolvedDetail = detail as string | undefined;
+
+  if (typeof resolvedDetail === 'string') {
+    const detailAlias = GET_NODE_DETAIL_ALIASES[resolvedDetail.toLowerCase()];
+    if (detailAlias) {
+      aliased.push(`detail=${resolvedDetail}→${detailAlias}`);
+      resolvedDetail = detailAlias;
+    }
+  }
+
+  if (typeof resolvedMode === 'string') {
+    const modeAlias = GET_NODE_MODE_ALIASES[resolvedMode.toLowerCase()];
+    if (modeAlias) {
+      // A retired mode value is the caller's statement of intent for the
+      // detail level too (mode=full meant "everything"), so it wins over a
+      // detail value that most clients only send because the schema defaults it.
+      const target = modeAlias.detail
+        ? `mode=${modeAlias.mode}, detail=${modeAlias.detail}`
+        : `mode=${modeAlias.mode}`;
+      aliased.push(`mode=${resolvedMode}→${target}`);
+      resolvedMode = modeAlias.mode;
+      if (modeAlias.detail) resolvedDetail = modeAlias.detail;
+    }
+  }
+
+  if (aliased.length > 0) {
+    logger.debug(`get_node: retired parameter vocabulary aliased (${aliased.join('; ')})`);
+  }
+
+  return { mode: resolvedMode, detail: resolvedDetail };
+}
+
+/**
+ * Suggestions for `n8n_executions` action values seen in telemetry that belong
+ * to other tools or to no tool. Returned text is appended to the unknown-action
+ * error so the caller can correct itself in one step.
+ */
+const EXECUTIONS_ACTION_HINTS: Record<string, string> = {
+  get_many: "Did you mean action='list'?",
+  getmany: "Did you mean action='list'?",
+  getall: "Did you mean action='list'?",
+  get_all: "Did you mean action='list'?",
+  list_executions: "Did you mean action='list'?",
+  listexecutions: "Did you mean action='list'?",
+  search: "Did you mean action='list'?",
+  get_execution: "Did you mean action='get'?",
+  getexecution: "Did you mean action='get'?",
+  retry: "Retrying an execution is not supported; re-run the workflow with n8n_test_workflow.",
+  list_runs: 'Evaluation test runs are managed by n8n_evaluations.',
+  get_run: 'Evaluation test runs are managed by n8n_evaluations.',
+  getrows: 'Data table rows are managed by n8n_manage_datatable.',
+  get_rows: 'Data table rows are managed by n8n_manage_datatable.',
+};
+
+export function suggestExecutionsAction(action: string): string | undefined {
+  return EXECUTIONS_ACTION_HINTS[action.toLowerCase()];
+}
+
+/**
+ * Agents send `id` and `workflowId` interchangeably for tools whose only
+ * identifier is a workflow id. Returns a copy of the arguments with
+ * `workflowId` filled from `id` when the canonical key is absent or blank.
+ * `id` is not a schema property, so the server's type coercion never sees it
+ * and a numeric value has to be accepted here.
+ */
+export function withWorkflowIdAlias<T extends Record<string, unknown>>(args: T): T {
+  if (typeof args.workflowId === 'string' && args.workflowId.trim() !== '') {
+    return args;
+  }
+  const id = typeof args.id === 'number' ? String(args.id) : args.id;
+  if (typeof id !== 'string' || id.trim() === '') {
+    return args;
+  }
+  return { ...args, workflowId: id };
+}

src/mcp/param-aliases.ts

@@ -10,6 +10,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolDefinition } from '../types';
+import type { McpToolResponse } from '../types/n8n-api';
 import { existsSync, readFileSync, promises as fs } from 'fs';
 import path from 'path';
 import { n8nDocumentationToolsFinal } from './tools';
@@ -20,11 +21,13 @@ import {
   getDisabledTools as getDisabledToolsPolicy,
   getDisabledToolOperations as getDisabledToolOperationsPolicy,
   getValidOperations,
+  isOperationDisabled,
   resolveRequestedOperation,
 } from './tool-policy';
 import { makeToolsN8nFriendly } from './tools-n8n-friendly';
 import { getWorkflowExampleString } from './workflow-examples';
 import { logger } from '../utils/logger';
+import { resolveGetNodeAliases, suggestExecutionsAction, withWorkflowIdAlias } from './param-aliases';
 import { installStdioGuard } from '../utils/stdio-guard';
 import { summarizeToolCallArgs } from '../utils/redaction';
 import { NodeRepository } from '../database/node-repository';
@@ -675,6 +678,9 @@ export class N8NDocumentationMCPServer {
       const param = cloned.inputSchema?.properties?.[paramName];
       if (param?.enum) {
         param.enum = (param.enum as string[]).filter(v => !ops.has(v.toLowerCase()));
+        if (typeof param.default === 'string' && ops.has(param.default.toLowerCase())) {
+          delete param.default;
+        }
         if (param.enum.length === 0) {
           logger.warn(
             `DISABLED_TOOL_OPERATIONS: all operations for '${toolName}' are disabled ` +
@@ -1291,10 +1297,19 @@ export class N8NDocumentationMCPServer {
         validationResult = ToolValidation.validateWorkflowId(args);
         break;
       case 'n8n_executions':
-        // Requires action parameter, id validation done in handler based on action
-        validationResult = args.action
+        // action defaults to list; id validation is done in dispatch based on action
+        validationResult = { valid: true, errors: [] };
+        break;
+      case 'n8n_test_workflow':
+        validationResult = typeof args.workflowId === 'string' && args.workflowId.trim() !== ''
           ? { valid: true, errors: [] }
-          : { valid: false, errors: [{ field: 'action', message: 'action is required' }] };
+          : {
+              valid: false,
+              errors: [{
+                field: 'workflowId',
+                message: 'workflowId is required: the ID of the workflow to run ("id" is accepted as an alias)'
+              }]
+            };
         break;
       case 'n8n_evaluations': {
         // Every action of this tool requires action and workflowId;
@@ -1576,6 +1591,26 @@ export class N8NDocumentationMCPServer {
     return coerced;
   }
 
+  /**
+   * `n8n_executions` with action=get but no execution id is the most frequent
+   * agent call error in telemetry, and the caller wants the listing. Serve it
+   * and say so, rather than failing the call.
+   */
+  private async listExecutionsInsteadOfGet(args: any): Promise<McpToolResponse> {
+    // The policy gate checked this call as `get`; the fallback must not open a
+    // listing that a DISABLED_TOOL_OPERATIONS rule has closed.
+    if (isOperationDisabled('n8n_executions', 'list')) {
+      throw new Error('id is required for action=get');
+    }
+    const result = await n8nHandlers.handleListExecutions(args, this.instanceContext);
+    if (!result.success) return result;
+    const scope = args.workflowId ? `executions of workflow ${args.workflowId}` : 'recent executions';
+    return {
+      ...result,
+      message: `action=get was called without an execution id, so ${scope} were listed instead. Pass id to get one execution.`
+    };
+  }
+
   async executeTool(name: string, args: any): Promise<any> {
     // Ensure args is an object and validate it
     args = args || {};
@@ -1628,13 +1663,15 @@ export class N8NDocumentationMCPServer {
           includeOperations: args.includeOperations,
           source: args.source
         });
-      case 'get_node':
+      case 'get_node': {
         this.validateToolParams(name, args, ['nodeType']);
+        // Retired get_node_essentials / get_node_info vocabulary maps onto mode + detail
+        const { mode: nodeMode, detail: nodeDetail } = resolveGetNodeAliases(args.mode, args.detail);
         // Handle consolidated modes: docs, search_properties
-        if (args.mode === 'docs') {
+        if (nodeMode === 'docs') {
           return this.getNodeDocumentation(args.nodeType);
         }
-        if (args.mode === 'search_properties') {
+        if (nodeMode === 'search_properties') {
           if (!args.propertyQuery) {
             throw new Error('propertyQuery is required for mode=search_properties');
           }
@@ -1643,13 +1680,14 @@ export class N8NDocumentationMCPServer {
         }
         return this.getNode(
           args.nodeType,
-          args.detail,
-          args.mode,
+          nodeDetail,
+          nodeMode,
           args.includeTypeInfo,
           args.includeExamples,
           args.fromVersion,
           args.toVersion
         );
+      }
       case 'validate_node':
         this.validateToolParams(name, args, ['nodeType', 'config']);
         // Ensure config is an object
@@ -1792,16 +1830,21 @@ export class N8NDocumentationMCPServer {
         await this.ensureInitialized();
         if (!this.repository) throw new Error('Repository not initialized');
         return n8nHandlers.handleAutofixWorkflow(args, this.repository, this.instanceContext);
-      case 'n8n_test_workflow':
-        this.validateToolParams(name, args, ['workflowId']);
-        return n8nHandlers.handleTestWorkflow(args, this.instanceContext);
+      case 'n8n_test_workflow': {
+        const testArgs = withWorkflowIdAlias(args);
+        this.validateToolParams(name, testArgs);
+        return n8nHandlers.handleTestWorkflow(testArgs, this.instanceContext);
+      }
       case 'n8n_executions': {
-        this.validateToolParams(name, args, ['action']);
-        const execAction = args.action;
+        this.validateToolParams(name, args);
+        // Agents that only want a listing often omit action or send get without an id.
+        // The same normalisation the policy gate uses, so a disabled-operation rule
+        // and the dispatch always see the same value.
+        const execAction = String(resolveRequestedOperation(name, args));
         switch (execAction) {
           case 'get':
             if (!args.id) {
-              throw new Error('id is required for action=get');
+              return this.listExecutionsInsteadOfGet(args);
             }
             return n8nHandlers.handleGetExecution(args, this.instanceContext);
           case 'list':
@@ -1811,8 +1854,11 @@ export class N8NDocumentationMCPServer {
               throw new Error('id is required for action=delete');
             }
             return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
-          default:
-            throw new Error(`Unknown action: ${execAction}. Valid actions: get, list, delete`);
+          default: {
+            const message = `Unknown action: ${execAction}. Valid actions: get, list, delete.`;
+            const hint = suggestExecutionsAction(execAction);
+            throw new Error(hint ? `${message} ${hint}` : message);
+          }
         }
       }
       case 'n8n_evaluations': {
@@ -1849,8 +1895,8 @@ export class N8NDocumentationMCPServer {
         }
         return n8nHandlers.handleHealthCheck(this.instanceContext);
       case 'n8n_workflow_versions':
-        this.validateToolParams(name, args, ['mode']);
-        return n8nHandlers.handleWorkflowVersions(args, this.repository!, this.instanceContext);
+        // mode defaults to list in the handler schema; workflowId is filled from id
+        return n8nHandlers.handleWorkflowVersions(withWorkflowIdAlias(args), this.repository!, this.instanceContext);
 
       case 'n8n_deploy_template':
         this.validateToolParams(name, args, ['templateId']);

src/mcp/server.ts

@@ -36,7 +36,7 @@ export const n8nExecutionsDoc: ToolDocumentation = {
 - Provides AI-friendly fix suggestions based on error patterns
 - Token-efficient (80-90% smaller than full mode)`,
     parameters: {
-      action: { type: 'string', required: true, description: 'Operation: "get", "list", or "delete"' },
+      action: { type: 'string', required: false, description: 'Operation: "get", "list" (default), or "delete". "get" without an id lists executions instead' },
       id: { type: 'string', required: false, description: 'Execution ID (required for action=get or action=delete)' },
       mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full", "error"' },
       nodeNames: { type: 'array', required: false, description: 'For action=get with mode=filtered: Filter to specific nodes by name' },

src/mcp/tool-docs/workflow_management/n8n-executions.ts

@@ -52,7 +52,7 @@ Every response states \`method\` and \`backend\` ('public-api' or 'official-mcp'
       workflowId: {
         type: 'string',
         required: true,
-        description: 'Workflow ID to execute'
+        description: 'Workflow ID to execute ("id" is accepted as an alias)'
       },
       method: {
         type: 'string',

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

@@ -97,8 +97,8 @@ per workflow, plus an age-based retention window). Native history retention is n
     parameters: {
       mode: {
         type: 'string',
-        required: true,
-        description: 'Operation mode: "list", "get", "rollback", "diff", "delete", or "prune"',
+        required: false,
+        description: 'Operation mode: "list" (default), "get", "rollback", "diff", "delete", or "prune"',
         enum: ['list', 'get', 'rollback', 'delete', 'prune', 'diff']
       },
       source: {