xlsx-for-ai 3.0.13 → 3.0.16

package/mcp.js

@@ -39,7 +39,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         format:    {
           type: 'string',
           enum: ['md', 'json', 'sql'],
@@ -64,7 +64,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -80,7 +80,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet:     { type: 'string', description: 'Limit to one sheet (default: all).' },
       },
       required: ['file_path'],
@@ -97,8 +97,8 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path_a: { type: 'string', description: 'Path to the base .xlsx file.' },
-        file_path_b: { type: 'string', description: 'Path to the changed .xlsx file.' },
+        file_path_a: { type: 'string', description: 'Absolute path to the base .xlsx file. Pass the path string AS-IS — do NOT base64-encode the file; the client reads it.' },
+        file_path_b: { type: 'string', description: 'Absolute path to the changed .xlsx file. Pass the path string AS-IS — do NOT base64-encode the file; the client reads it.' },
         sheet:       { type: 'string', description: 'Limit diff to one sheet (default: all).' },
       },
       required: ['file_path_a', 'file_path_b'],
@@ -181,7 +181,7 @@ const TOOLS = [
         },
         spec_path: {
           type: 'string',
-          description: 'Path to a .json file carrying the spec (alternative to inline spec for large workbooks).',
+          description: 'Absolute path to a .json file carrying the spec (alternative to inline spec for large workbooks). Pass the path string AS-IS — do NOT base64-encode; the client reads it.',
         },
         out_path: {
           type: 'string',
@@ -189,7 +189,7 @@ const TOOLS = [
         },
         base_file_b64: {
           type: 'string',
-          description: 'Optional base64 of an existing .xlsx to edit-in-place. When omitted, a fresh workbook is created.',
+          description: 'NARROW EXCEPTION — xlsx_write ONLY accepts a base64-encoded base workbook here for edit-in-place. Every OTHER tool in this connector takes a file PATH (`file_path`), not bytes. When omitted, a fresh workbook is created.',
         },
       },
       // out_path is the typical caller's choice but not strictly required —
@@ -212,7 +212,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the source .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the source .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O.' },
         out_path:  { type: 'string', description: 'Destination for the redacted .xlsx file.' },
       },
       required: ['file_path', 'out_path'],
@@ -238,7 +238,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path:  { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path:  { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet:      { type: 'string', description: 'Sheet name (default: first sheet).' },
         header_row: { type: 'integer', description: 'Header row (1-based). 0 = treat row 1 as data, no header.' },
         max_rows:   { type: 'integer', description: 'Max data rows to scan (default 10000).' },
@@ -258,7 +258,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path:  { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path:  { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         predicates: {
           type: 'array',
           minItems: 1,
@@ -292,7 +292,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         group_by:  { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Columns to group by.' },
         aggs:      {
           type: 'array',
@@ -328,7 +328,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -344,7 +344,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         by:        {
           type: 'array',
           minItems: 1,
@@ -376,7 +376,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         column:    { type: 'string', description: 'Column to count values in.' },
         sheet:     { type: 'string' },
         header_row:    { type: 'integer' },
@@ -398,7 +398,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet:     { type: 'string', description: 'Filter to one sheet (default: all sheets).' },
         include_results: { type: 'boolean', description: 'Include cached results column (default true).' },
         limit:     { type: 'integer', description: 'Max formulas to return (default 1000, max 5000).' },
@@ -418,7 +418,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet:     { type: 'string', description: 'Filter to one sheet (default: all sheets).' },
         include_columns: { type: 'boolean', description: 'Include column names per table (default true).' },
       },
@@ -436,7 +436,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         index:     { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Row-axis grouping columns.' },
         columns:   { type: 'array', items: { type: 'string' }, description: 'Column-axis grouping columns (optional).' },
         values:    { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Columns to aggregate.' },
@@ -460,7 +460,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         formulas: {
           type: 'array',
           items: { type: 'string' },
@@ -488,7 +488,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the source spreadsheet file (any supported format).' },
+        file_path: { type: 'string', description: 'Absolute path to the source spreadsheet file (any supported format). Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O.' },
         to: {
           type: 'string',
           enum: [
@@ -516,7 +516,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         mode: {
           type: 'string',
           enum: ['diagnose', 'execute'],
@@ -577,7 +577,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -594,7 +594,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -612,7 +612,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -630,7 +630,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -647,7 +647,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -665,7 +665,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -682,7 +682,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx / .xlsm file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx / .xlsm file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O.' },
       },
       required: ['file_path'],
     },
@@ -699,7 +699,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -716,7 +716,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx / .xlsm / .xlsb file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx / .xlsm / .xlsb file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O.' },
       },
       required: ['file_path'],
     },
@@ -733,7 +733,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -750,7 +750,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -768,7 +768,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -785,7 +785,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -802,7 +802,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -818,7 +818,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
       },
       required: ['file_path'],
     },
@@ -834,7 +834,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -851,7 +851,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -868,7 +868,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -885,7 +885,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
       },
       required: ['file_path'],
@@ -903,7 +903,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file. Pass the path string AS-IS — do NOT read, open, or base64-encode the file; the client handles all file I/O. The base64 surface in this connector is OUTPUT-only (_meta.file_b64).' },
         sheet: { type: 'string', description: 'Optional: restrict to a specific sheet.' },
         detailed: { type: 'boolean', description: 'If true, return per-cell breakdown (capped at 1000 cells). Default false (per-sheet rollup).' },
       },
@@ -1501,6 +1501,21 @@ function friendlyErrorMessage(toolName, err) {
       return `${toolName}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
     case 'FALLBACK_ENGINE_MISSING':
       return `${toolName}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
+    case 'BASE64_MISREAD':
+      // SPM SPEC base64-defensive-error-and-suggested-next-call — turn the
+      // base64-bash-hang class into a one-turn recovery. The error names
+      // the offending field AND restates the contract so the next call
+      // self-corrects.
+      return (
+        `${toolName}: argument "${err.field || 'file_path'}" looks like base64-encoded bytes, not a file path. ` +
+        `This tool takes a PATH STRING (e.g. "/Users/you/foo.xlsx" or "~/Desktop/foo.xlsx"); the client reads and encodes the file for you. ` +
+        `Retry with file_path set to the path string.`
+      );
+    case 'MISSING_REQUIRED_ARG':
+      return (
+        `${toolName}: missing required argument "${err.field || ''}". ` +
+        `Check the tool's input schema; the workhorse case is file_path as a path string (NOT bytes).`
+      );
     default:
       break;
   }
@@ -1559,7 +1574,148 @@ function friendlyErrorMessage(toolName, err) {
 // Tool dispatch
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Defensive input-contract validation (belt-and-suspenders for SPM SPEC
+// base64-defensive-error-and-suggested-next-call).
+//
+// Description hardening in 3.0.14 reduces the rate at which the model
+// invents a base64-encoding step, but doesn't eliminate it. If a tool
+// call arrives with byte-shaped content where a file_path is expected,
+// or with file_path missing entirely, throw a crisp error code the
+// friendlyErrorMessage path translates into actionable text — turning
+// the prior indefinite hang into a one-turn recovery.
+// ---------------------------------------------------------------------------
+
+const FILE_PATH_FIELDS = new Set(['file_path', 'file_path_a', 'file_path_b', 'spec_path']);
+const BASE64_ONLY_REGEX = /^[A-Za-z0-9+/]+=*$/;
+
+function looksLikeBase64(value) {
+  if (typeof value !== 'string') return false;
+  // The trap: `/` is a base64-alphabet character AND a POSIX path
+  // separator, so "contains slash" can't distinguish on its own. Real
+  // file paths carry distinctive markers base64 strings don't:
+  //   - `.` for an extension (any spreadsheet path ends with .xlsx/.xls/
+  //     etc; intermediate dirs often have them too)
+  //   - `\` for Windows path separators
+  //   - `~` for home prefix
+  //   - spaces (common in Mac/Windows user dirs)
+  // If ANY of those appear, we treat the string as a path.
+  if (value.length < 200) return false;
+  if (
+    value.includes('.') ||
+    value.includes('\\') ||
+    value.includes('~') ||
+    value.includes(' ')
+  ) {
+    return false;
+  }
+  const trimmed = value.trim();
+  return BASE64_ONLY_REGEX.test(trimmed);
+}
+
+function validateToolArgs(name, args) {
+  // Find the tool's inputSchema so we can read the `required` array. Use a
+  // local Map lookup so a 50-tool catalog isn't re-scanned per call.
+  if (!validateToolArgs._toolByName) {
+    validateToolArgs._toolByName = new Map(TOOLS.map((t) => [t.name, t]));
+  }
+  const tool = validateToolArgs._toolByName.get(name);
+  if (!tool || !tool.inputSchema) return; // unknown tool — server will route or fail
+  const schema = tool.inputSchema;
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const argsObj = args && typeof args === 'object' ? args : {};
+
+  // Required-field presence check.
+  for (const field of required) {
+    const v = argsObj[field];
+    if (v === undefined || v === null || (typeof v === 'string' && v.length === 0)) {
+      const err = new Error(`${name}: missing required argument "${field}".`);
+      err.code = 'MISSING_REQUIRED_ARG';
+      err.field = field;
+      throw err;
+    }
+  }
+
+  // Base64-misread check on every file_path-shaped field.
+  for (const field of FILE_PATH_FIELDS) {
+    if (!(field in argsObj)) continue;
+    if (looksLikeBase64(argsObj[field])) {
+      const err = new Error(
+        `${name}: argument "${field}" looks like base64-encoded bytes, not a file path.`
+      );
+      err.code = 'BASE64_MISREAD';
+      err.field = field;
+      throw err;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Suggested-next-call injection on triage tools (SPM SPEC follow-up).
+//
+// xlsx_doctor's findings reference follow-on tools by name ("Run
+// xlsx_workbook_views to enumerate", "Run xlsx_external_links to see
+// the target"). Post-process the response text to add a concrete
+// invocation example for each referenced tool — pre-filled with the
+// caller's file_path. Doubles as a correct-usage exemplar (path-shaped,
+// no base64) that mitigates the misread class structurally.
+// ---------------------------------------------------------------------------
+
+// Tools that take ONLY a required file_path — safe to suggest with a
+// one-arg invocation.
+const _drillDownEligible = (() => {
+  const map = new Map();
+  for (const t of TOOLS) {
+    const req = Array.isArray(t.inputSchema?.required) ? t.inputSchema.required : [];
+    if (req.length === 1 && req[0] === 'file_path') map.set(t.name, true);
+  }
+  return map;
+})();
+
+function injectDrillDownExamples(result, callerToolName, args) {
+  if (!result || typeof result !== 'object') return result;
+  if (!args || typeof args.file_path !== 'string' || args.file_path.length === 0) return result;
+  const content = Array.isArray(result.content) ? result.content : null;
+  if (!content) return result;
+  // First text block holds the rendered findings.
+  const firstText = content.find((c) => c && c.type === 'text' && typeof c.text === 'string');
+  if (!firstText) return result;
+
+  // Scan for xlsx_FOO mentions OTHER than the caller itself.
+  const mentioned = new Set();
+  const re = /\bxlsx_[a-z_]+(?:_[a-z_]+)*\b/g;
+  let m;
+  while ((m = re.exec(firstText.text)) !== null) {
+    const tool = m[0];
+    if (tool === callerToolName) continue;
+    if (_drillDownEligible.has(tool)) mentioned.add(tool);
+  }
+  if (mentioned.size === 0) return result;
+
+  const filePathJson = JSON.stringify(args.file_path);
+  const lines = [...mentioned].sort().map(
+    (toolName) => `- \`${toolName}({ "file_path": ${filePathJson} })\``
+  );
+  const footer =
+    '\n\n---\nDrill-down suggestions — concrete invocations pre-filled with your file_path ' +
+    '(pass the path STRING, not file bytes; the client reads the file):\n' +
+    lines.join('\n');
+
+  // Return a new result object with the footer appended; do NOT mutate the
+  // server's response.
+  const newContent = content.map((c) => {
+    if (c === firstText) return { ...c, text: c.text + footer };
+    return c;
+  });
+  return { ...result, content: newContent };
+}
+
 async function dispatchTool(name, args) {
+  // Defensive validation — runs first so a base64 misread or missing
+  // file_path produces an actionable error instead of an opaque server
+  // failure or a base64-bash-hang.
+  validateToolArgs(name, args);
+
   // xlsx_read: relay to API; fallback to local on unreachable / 5xx
   if (name === 'xlsx_read') {
     const body = {
@@ -1954,7 +2110,14 @@ async function dispatchTool(name, args) {
     file_b64: fileToB64(args.file_path),
     options: opts,
   };
-  return callTool(name, body);
+  const result = await callTool(name, body);
+
+  // Triage tools that mention follow-on tools in their findings get a
+  // drill-down footer with pre-filled invocations. xlsx_doctor is the
+  // primary triage surface; xlsx_topology and xlsx_doctor's siblings can
+  // benefit too, so we run the injection universally — it's a no-op on
+  // any response whose text doesn't mention other xlsx_* tools.
+  return injectDrillDownExamples(result, name, args);
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "3.0.13",
+  "version": "3.0.16",
   "description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
   "main": "index.js",
   "bin": {