xlsx-for-ai 3.0.0 → 3.0.4

package/README.md

@@ -1,10 +1,8 @@
 # xlsx-for-ai
 
-> **⚠️ MCP users on 2.25.0–2.26.0: upgrade.** Those versions crash the MCP server on startup (missing `lib/annotations.js`, fixed in 2.26.1). Run `npm install -g xlsx-for-ai@latest` and restart your MCP client. Or switch to the `npx -y` config snippets below so future versions self-heal on every restart.
-
 **The missing reliability layer that makes spreadsheet reasoning production-grade for LLMs.**
 
-A thin npm client over a hosted API. Install once, add to your agent config, and your agent gets 48 production-grade tools for reading, writing, diffing, redacting, healing, and cryptographically attesting `.xlsx` files — engine complexity runs server-side, engine IP stays private.
+A thin npm client over a hosted API. Install once, add to your agent config, and your agent gets 50 production-grade tools for reading, writing, diffing, redacting, healing, and cryptographically attesting `.xlsx` files — engine complexity runs server-side, engine IP stays private.
 
 ```bash
 npm install -g xlsx-for-ai
@@ -24,7 +22,7 @@ Add `xlsx-for-ai` as a tool server in your agent runtime. First invocation auto-
 
 **Easiest: one-click install via the `.mcpb` bundle.** Download and drag into Claude Desktop (Settings → Extensions):
 
-**[xlsx-for-ai-2.0.0.mcpb](https://github.com/senoff/xlsx-for-ai/releases/latest/download/xlsx-for-ai-2.0.0.mcpb)** *(latest release)*
+**[xlsx-for-ai.mcpb](https://github.com/senoff/xlsx-for-ai/releases/latest/download/xlsx-for-ai.mcpb)** *(latest release — version-agnostic stable filename, always serves the current bundle)*
 
 The bundle includes the full npm package and registers all MCP tools automatically. No manual config edits needed.
 
@@ -41,7 +39,7 @@ The bundle includes the full npm package and registers all MCP tools automatical
 }
 ```
 
-Verify either path: restart Claude Desktop, open a new conversation, and ask "what MCP tools do you have?" — 48 `xlsx_*` tools should appear, including `xlsx_doctor` (one-call health report — try it first on any unknown workbook).
+Verify either path: restart Claude Desktop, open a new conversation, and ask "what MCP tools do you have?" — 50 `xlsx_*` tools should appear, including `xlsx_doctor` (one-call health report — try it first on any unknown workbook).
 
 ### Cursor
 
@@ -58,7 +56,7 @@ Config file: `~/.cursor/mcp.json`
 }
 ```
 
-Verify: open Cursor settings → MCP → confirm `xlsx-for-ai` shows 6 tools.
+Verify: open Cursor settings → MCP → confirm `xlsx-for-ai` shows 50 `xlsx_*` tools.
 
 ### Continue
 
@@ -93,7 +91,7 @@ Pass `--mcp-server` on the command line, or add to your Codex config:
 }
 ```
 
-Verify: run `codex --list-tools` and confirm the six xlsx tools are listed.
+Verify: run `codex --list-tools` and confirm 50 `xlsx_*` tools are listed.
 
 ### Zed
 
@@ -139,7 +137,7 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 
 ## What it does
 
-48 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
+50 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
 
 ### Triage / orient
 
@@ -158,11 +156,14 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | Tool | What it does |
 |---|---|
 | `xlsx_read` | Read a workbook — text, JSON, or markdown. Formulas, named ranges, layout, and data types preserved. |
+| `xlsx_read_handle` | Read by server-side handle instead of bytes — for session flows where the workbook has already been uploaded and shouldn't be transferred again. |
 | `xlsx_write` | Create or update a workbook from a structured spec. Multi-sheet, formulas, named ranges, table definitions. |
+| `xlsx_data_clean` | Normalize messy data in place — trim whitespace, coerce types, dedupe rows, fix obvious encoding artifacts. Returns a cleaned copy + a change log. Save-As shape; never mutates the input. |
 | `xlsx_diff` | Semantic diff between two workbooks — cell-level deltas, formula changes, structural shifts. Deterministic output. |
 | `xlsx_redact` | Redact PII from a workbook before sharing. Server-side detection; returns redacted copy plus audit manifest. |
 | `xlsx_convert` | 25+ in / 16 out formats (csv, tsv, html, ods, xls, xlsb, dif, sylk, prn, txt, dbf, eth, json, markdown, xlsx, etc.). |
 | `xlsx_validate` | Cross-engine consistency check — runs the workbook through TWO independent renderers and reports cell-level divergences. |
+| `xlsx_session_set_validations` | Configure per-session validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns). Stateful — affects this session only. |
 
 ### Pandas-parity (compute fresh aggregates)
 
@@ -214,6 +215,17 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | `xlsx_receipt` | Attach an AI-generation receipt — Ed25519-signed claims describing the caller-declared agent identity (name, display name, identity URL), generation timestamp, content hash, optional source-file hashes, optional prompt hash, optional MCP tools called, and an optional description. Honesty boundary (load-bearing): the server signs the caller-declared `agent.name` — it does NOT verify the caller actually IS that agent. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope. |
 | `xlsx_verify_receipt` | Verify a workbook's embedded receipt. Returns the same three trust signals as `xlsx_verify_stamp` plus the caller-declared agent identity AS declared (no UI affordances implying cryptographic identity verification). Use to surface "where did this file come from?" — backed by the server's signature over caller honest declaration. |
 
+### Healer — external-reference breakage
+
+Workbooks rot. A file moves and `#REF!` propagates through every dependent formula. A Power Query connection embeds credentials nobody can rotate. A defined name points at an external workbook that doesn't exist anymore. The healer family diagnoses these classes and applies targeted cures — read-only diagnosis, simulated-before-applied repair, and a high-level intent path when the agent doesn't want to spell out individual cure operations.
+
+| Tool | What it does |
+|---|---|
+| `xlsx_healer_diagnose` | Structured report of external-reference breakage — broken external refs, defined-name external refs, Power Query connections with embedded credentials, `#REF!` propagation maps, multi-hop chains. Read-only. |
+| `xlsx_healer_simulate` | Show what a specific cure operation would change before applying it — same shape as `xlsx_healer_cure` but read-only. Use to preview impact when the agent is uncertain whether to proceed. |
+| `xlsx_healer_cure` | Apply ONE specific cure operation (e.g., strip broken external refs, harmonize a defined name, replace `#REF!` propagation with a deterministic value). Save-As shape; the source workbook is preserved unless `confirm:true` is set with `mode:"in_place"`. |
+| `xlsx_healer_intent` | High-level intent path — `make-it-work`, `make-standalone`, `migrate` — translated into the right sequence of cure ops. For when the agent knows the goal but not the operation. |
+
 Tool responses include a citation footer and a `_meta` block (tool name, version, tier, request ID, `powered_by`). Both pass through verbatim; nothing is stripped.
 
 ---
@@ -275,7 +287,7 @@ Annual-only — kills churn ops overhead. All paid tiers include every tool (`xl
 
 | Tier | Price | File cap | Calls/mo | Notes |
 |---|---|---|---|---|
-| Free | $0 | 10 MB | 10,000 | Anonymous UUID registration. All 36 read-only tools. Non-commercial use. |
+| Free | $0 | 10 MB | 10,000 | Anonymous UUID registration. All 39 read-only tools. Non-commercial use. |
 | Bronze | $29/yr | 25 MB | 20,000 | Commercial use. + `xlsx_validate` cross-engine check. |
 | Silver | $99/yr | 50 MB | 40,000 | Same surface, higher caps. |
 | Gold | $199/yr | 100 MB | 100,000 | Same surface, highest caps for solo users. |

package/lib/annotations.js

@@ -116,7 +116,53 @@ function applyAnnotations(tools) {
   });
 }
 
+/**
+ * Sanitize an MCP-shaped tool array so every entry has the fields the MCP
+ * spec requires for client registration: `name` (already required), plus a
+ * non-empty `inputSchema` and a non-empty `description`.
+ *
+ * Floor strategy:
+ *   - If `inputSchema` is missing or not an object, substitute the permissive
+ *     `{ type: 'object' }`. Claude Desktop and other strict clients drop
+ *     tools without an inputSchema; the permissive object schema is enough
+ *     for them to REGISTER the tool. Real per-arg schemas are upstream
+ *     (server-side /api/v1/tools/list) work; this is the unblocking floor.
+ *   - If `description` is missing or empty, substitute the annotation title
+ *     (if any) or a generic `xlsx-for-ai tool: <name>` so the tool surfaces
+ *     in client UIs that key off description text.
+ *   - Tools without a `name` field are dropped (the MCP spec requires it
+ *     and dispatch would have nothing to route by anyway).
+ *
+ * SPM P0 2026-06-05 (mcp-toolslist-missing-inputschema). The hosted
+ * /api/v1/tools/list endpoint currently returns minimal entries
+ * ({name, category, maturity_state, endpoint}); the field-level mergeTools
+ * upstream of this preserves the baked-in inputSchema/description for the
+ * names the client ships, but server-only tools (e.g. newer additions not
+ * yet in the baked TOOLS array) still need a floor so they don't poison
+ * the whole tools/list.
+ */
+function sanitizeForMcp(tools) {
+  if (!Array.isArray(tools)) return [];
+  const out = [];
+  for (const t of tools) {
+    if (!t || typeof t.name !== 'string' || !t.name) continue;
+    const fixed = { ...t };
+    if (!fixed.inputSchema || typeof fixed.inputSchema !== 'object' || Array.isArray(fixed.inputSchema)) {
+      fixed.inputSchema = { type: 'object' };
+    }
+    if (!fixed.description || typeof fixed.description !== 'string') {
+      const annTitle = fixed.annotations && typeof fixed.annotations.title === 'string'
+        ? fixed.annotations.title
+        : null;
+      fixed.description = annTitle || `xlsx-for-ai tool: ${fixed.name}`;
+    }
+    out.push(fixed);
+  }
+  return out;
+}
+
 module.exports = {
   TOOL_ANNOTATIONS,
   applyAnnotations,
+  sanitizeForMcp,
 };

package/lib/discover.js

@@ -106,19 +106,35 @@ async function fetchRemoteCatalog() {
 }
 
 /**
- * mergeTools: server catalog wins on name collision; baked-in tools fill gaps.
- * Order: every remote tool first (preserving server order), then any baked-in
- * tool whose name isn't in the remote set. This way the most up-to-date
- * description always wins, but we never lose a tool the client knows how to
- * dispatch even if the server temporarily forgets it.
+ * mergeTools: server catalog wins on name collision, but FIELD-BY-FIELD —
+ * the remote response only overwrites fields it actually provides. The
+ * baked-in description + inputSchema survive when the server returns a
+ * minimal manifest (which is exactly what /api/v1/tools/list does today:
+ * {name, category, maturity_state, endpoint} only).
+ *
+ * Without this, Claude Desktop receives a tools/list whose entries have no
+ * inputSchema and silently drops the whole array — tools panel empty, no
+ * tools/call ever fires. SPM P0 2026-06-05 (mcp-toolslist-missing-inputschema).
+ *
+ * Order: remote tools first (preserving server order), then any baked-in
+ * tool whose name isn't in the remote set. That way the server can still
+ * remove a tool, and a tool the client knows how to dispatch survives a
+ * server forgetting it.
  */
 function mergeTools(remote, baked) {
+  const bakedByName = new Map();
+  for (const t of baked) {
+    if (t && typeof t.name === 'string') bakedByName.set(t.name, t);
+  }
   const out = [];
   const seen = new Set();
   for (const t of remote) {
     if (!t || typeof t.name !== 'string') continue;
     if (seen.has(t.name)) continue;  // dedupe within remote too — first wins
-    out.push(t);
+    const bakedTool = bakedByName.get(t.name);
+    // {...baked, ...remote}: remote wins on every field it actually has;
+    // baked fills in fields remote omits (description, inputSchema).
+    out.push(bakedTool ? { ...bakedTool, ...t } : t);
     seen.add(t.name);
   }
   for (const t of baked) {

package/mcp.js

@@ -17,7 +17,7 @@ const { ensureRegistered } = require('./lib/register');
 const { callTool }         = require('./lib/client');
 const { fallbackRead }     = require('./lib/fallback-read');
 const { resolveCatalog }   = require('./lib/discover');
-const { applyAnnotations } = require('./lib/annotations');
+const { applyAnnotations, sanitizeForMcp } = require('./lib/annotations');
 const fs                   = require('fs');
 const fsPromises           = require('fs/promises');
 const path                 = require('path');
@@ -30,8 +30,7 @@ const TOOLS = [
   {
     name: 'xlsx_read',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: read an .xlsx file from the LOCAL filesystem and return a rendered markdown/JSON/SQL representation.\n' +
+      'read an .xlsx file from the LOCAL filesystem and return a rendered markdown/JSON/SQL representation.\n' +
       'DEFAULT returns ALL sheets in one response — do not re-call per-sheet. Pass sheet="<name>" only when you specifically need to filter.\n' +
       'Pass format="md" (default — markdown table), "json" (structured rows), or "sql" (CREATE TABLE + INSERTs).\n' +
       'Synonyms accepted: "markdown" maps to "md", "text" maps to "md". Use the short forms to avoid guessing.\n\n' +
@@ -58,8 +57,7 @@ const TOOLS = [
   {
     name: 'xlsx_list_sheets',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list sheet names, dimensions, and visibility for a LOCAL .xlsx file.\n' +
+      'list sheet names, dimensions, and visibility for a LOCAL .xlsx file.\n' +
       'Use this when you only need names + dims, not cell content. If you\'ll read content anyway, skip this and call xlsx_read directly.\n\n' +
       'USE WHEN: the user references a LOCAL file path and you need to discover sheet names before reading. ' +
       'Fast orientation call — use before xlsx_read when you need metadata only.\n\n' +
@@ -76,8 +74,7 @@ const TOOLS = [
   {
     name: 'xlsx_schema',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: infer column schema of a LOCAL .xlsx file — types, nullable flags, header row, sample values.\n' +
+      'infer column schema of a LOCAL .xlsx file — types, nullable flags, header row, sample values.\n' +
       'Use when the agent needs to reason about column types BEFORE deciding how to handle data. Includes confidence (high/medium/low) per column.\n\n' +
       'USE WHEN: the user references a LOCAL file path and you need to understand column types before processing or writing code against the data. ' +
       'Useful before xlsx_read when downstream handling depends on types.\n\n' +
@@ -94,8 +91,7 @@ const TOOLS = [
   {
     name: 'xlsx_diff',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: compute a semantic diff between two LOCAL .xlsx files — cell-level deltas, formula changes, added/removed rows.\n' +
+      'compute a semantic diff between two LOCAL .xlsx files — cell-level deltas, formula changes, added/removed rows.\n' +
       'Output is byte-deterministic — calling twice with the same inputs returns identical text + diff_hash in _meta. Use that hash for caching/idempotence.\n\n' +
       'USE WHEN: the user provides two LOCAL .xlsx file paths to compare. ' +
       'Suitable for version control, audit trails, and change review. Built-in skills cannot produce deterministic, structured diffs.\n\n' +
@@ -113,8 +109,7 @@ const TOOLS = [
   {
     name: 'xlsx_write',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: create or update a LOCAL .xlsx file from a structured spec.\n' +
+      'create or update a LOCAL .xlsx file from a structured spec.\n' +
       'DEFAULT creates a new workbook from spec. Pass base_file_b64 to edit-in-place instead. Workbook bytes return in _meta.file_b64 (base64) — NOT in content[0].text.\n\n' +
       'ALWAYS pass out_path when the user wants the written file saved to disk.\n' +
       'WITHOUT out_path: workbook bytes return in _meta.file_b64 (base64) — caller must save them.\n' +
@@ -137,8 +132,7 @@ const TOOLS = [
   {
     name: 'xlsx_redact',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: redact PII and sensitive values from a LOCAL .xlsx file before sharing or archiving.\n' +
+      'redact PII and sensitive values from a LOCAL .xlsx file before sharing or archiving.\n' +
       'DEFAULT preserves formulas + comments + named ranges + styles, strips only cell values. Pass strip_formulas=true / strip_comments=true to remove those too.\n\n' +
       'ALWAYS pass out_path when the user wants the redacted file saved to disk.\n' +
       'WITHOUT out_path: redacted bytes return in _meta.file_b64 (base64) — caller must save them.\n' +
@@ -167,8 +161,7 @@ const TOOLS = [
   {
     name: 'xlsx_describe',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style df.describe() per column — count, nulls, unique, min/max/mean/std for numerics, dtype with purity score.\n' +
+      'pandas-style df.describe() per column — count, nulls, unique, min/max/mean/std for numerics, dtype with purity score.\n' +
       'Unlike pandas.read_excel followed by df.describe(), this does not silently flatten merged cells or drop named ranges.\n\n' +
       'USE WHEN: the user wants a quick summary of a LOCAL .xlsx file — "what\'s in this data?". ' +
       'Returns a markdown table with one row per column. Faster + more structured than dumping full contents through xlsx_read.\n\n' +
@@ -188,8 +181,7 @@ const TOOLS = [
   {
     name: 'xlsx_filter',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style row filter on a LOCAL .xlsx file with predicates AND-combined: eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null.\n' +
+      'pandas-style row filter on a LOCAL .xlsx file with predicates AND-combined: eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null.\n' +
       'Operates on real cell values — formulas evaluated server-side, not the cached results that pandas trusts blindly.\n\n' +
       'USE WHEN: the user asks for "rows where X" / "show me only Y" against a LOCAL .xlsx file. ' +
       'Returns matching rows as a markdown table, capped at 1000 rows by default with the actual match count.\n\n' +
@@ -223,8 +215,7 @@ const TOOLS = [
   {
     name: 'xlsx_aggregate',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style df.groupby([cols]).agg({col: func}) on a LOCAL .xlsx file. funcs: sum / mean / min / max / count / count_distinct.\n' +
+      'pandas-style df.groupby([cols]).agg({col: func}) on a LOCAL .xlsx file. funcs: sum / mean / min / max / count / count_distinct.\n' +
       'Type-aware: numeric aggregations skip non-numeric values cleanly instead of pandas\' silent NaN promotion.\n\n' +
       'USE WHEN: the user asks "what\'s the total / average / count of X by Y?" on a LOCAL .xlsx file. ' +
       'Returns one row per group with the requested aggregations as a markdown table.\n\n' +
@@ -260,8 +251,7 @@ const TOOLS = [
   {
     name: 'xlsx_named_ranges',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list all defined names (named ranges) in a LOCAL .xlsx workbook — name, scope (workbook or sheet), kind (cell / range / formula), reference.\n' +
+      'list all defined names (named ranges) in a LOCAL .xlsx workbook — name, scope (workbook or sheet), kind (cell / range / formula), reference.\n' +
       'pandas.read_excel collapses named ranges into anonymous ranges; this tool surfaces them so the agent can reason about formulas like =NPV(DiscountRate, Cashflows) before reading data.\n\n' +
       'USE WHEN: the agent is reasoning about a financial / engineering model and needs to know what cells named-range references resolve to. ' +
       'Call before xlsx_read to orient.\n\n' +
@@ -278,8 +268,7 @@ const TOOLS = [
   {
     name: 'xlsx_sort',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style df.sort_values() on a LOCAL .xlsx file with multi-column sort and per-column direction (asc/desc, default asc).\n' +
+      'pandas-style df.sort_values() on a LOCAL .xlsx file with multi-column sort and per-column direction (asc/desc, default asc).\n' +
       'Stable across all sort keys; type-aware comparison; nulls always sort last.\n\n' +
       'USE WHEN: the user wants rows ordered by one or more columns. Returns the sorted rows as a markdown table.\n\n' +
       'DO NOT USE WHEN: the data is already sorted as desired (use xlsx_read). Or for upload/attached files.',
@@ -311,8 +300,7 @@ const TOOLS = [
   {
     name: 'xlsx_value_counts',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style Series.value_counts() on one column of a LOCAL .xlsx file — count each unique value, sorted by frequency desc, with percentage.\n' +
+      'pandas-style Series.value_counts() on one column of a LOCAL .xlsx file — count each unique value, sorted by frequency desc, with percentage.\n' +
       'Excludes nulls by default; pass include_nulls=true to count them.\n\n' +
       'USE WHEN: the user asks "what\'s the distribution of X?" / "how often does each value appear?". Returns a markdown table.\n\n' +
       'DO NOT USE WHEN: the user wants groupby + multi-column aggregations (use xlsx_aggregate). Or for upload/attached files.',
@@ -333,8 +321,7 @@ const TOOLS = [
   {
     name: 'xlsx_formulas',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: extract every formula in a LOCAL .xlsx workbook — cell coord (A1), formula text, cached result. openpyxl-style read-only metadata.\n' +
+      'extract every formula in a LOCAL .xlsx workbook — cell coord (A1), formula text, cached result. openpyxl-style read-only metadata.\n' +
       'Distinct from xlsx_read which returns evaluated values; this returns the formulas themselves so an agent can audit, transform, or rewrite them.\n\n' +
       'USE WHEN: the user wants to see what formulas a workbook uses — spot-checking a model, auditing references, debugging unexpected results. ' +
       'pandas cannot extract formulas; this is the only way for an agent to see them.\n\n' +
@@ -354,8 +341,7 @@ const TOOLS = [
   {
     name: 'xlsx_tables',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every Excel ListObject ("Format as Table" structures) in a LOCAL .xlsx workbook — name, sheet, range, header/totals flags, columns.\n' +
+      'list every Excel ListObject ("Format as Table" structures) in a LOCAL .xlsx workbook — name, sheet, range, header/totals flags, columns.\n' +
       'pandas cannot see ListObjects; if a workbook uses Excel Tables, this is the only way to enumerate them.\n\n' +
       'USE WHEN: the user references a "table" in a workbook by name, or you need to know what structured tables exist before reading. ' +
       'Useful for workbooks with multiple tables on one sheet.\n\n' +
@@ -374,8 +360,7 @@ const TOOLS = [
   {
     name: 'xlsx_pivot',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: pandas-style pivot_table() on a LOCAL .xlsx file — reshape a flat table into a 2D matrix where rows are unique values of `index`, columns are unique values of `columns`, and cells are an aggregation of `values`.\n' +
+      'pandas-style pivot_table() on a LOCAL .xlsx file — reshape a flat table into a 2D matrix where rows are unique values of `index`, columns are unique values of `columns`, and cells are an aggregation of `values`.\n' +
       'agg modes: sum / mean / min / max / count / count_distinct. Optional fill_value for missing index×column combinations.\n\n' +
       'USE WHEN: the user wants a cross-tab — "X by Y", "rows by columns" — that needs more than groupby. Returns a markdown table.\n\n' +
       'DO NOT USE WHEN: there\'s only one grouping dimension (use xlsx_aggregate). Or for upload/attached files.',
@@ -398,8 +383,7 @@ const TOOLS = [
   {
     name: 'xlsx_eval',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: evaluate Excel formulas against a LOCAL .xlsx file via HyperFormula. xlwings-style.\n' +
+      'evaluate Excel formulas against a LOCAL .xlsx file via HyperFormula. xlwings-style.\n' +
       'Two modes: pass `formulas` (array of "=SUM(A1:A10)" expressions to compute against the workbook) or `cells` (array of "Sheet1!A1" cell refs to fresh-evaluate). Replaces pandas\' "trust the cached value" behavior with a real eval — if the cache is stale or missing, this still produces the right answer.\n\n' +
       'USE WHEN: the user wants the live computed value of a formula, not the cached one. Or when a workbook has formulas that depend on external data the cache might be stale on. ' +
       'Engine omits INDIRECT/HYPERLINK/WEBSERVICE/RTD/DDE by design — no I/O risk.\n\n' +
@@ -427,8 +411,7 @@ const TOOLS = [
   {
     name: 'xlsx_convert',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: universal spreadsheet format converter. Reads ANY of 25+ input formats (xlsx, xlsb, xlsm, xls, ods, fods, numbers, csv, tsv, dbf, lotus 1-2-3, quattro pro, sylk, dif, html, rtf, etc.) and emits ANY supported output format (xlsx, csv, json, md, html, etc.).\n' +
+      'universal spreadsheet format converter. Reads ANY of 25+ input formats (xlsx, xlsb, xlsm, xls, ods, fods, numbers, csv, tsv, dbf, lotus 1-2-3, quattro pro, sylk, dif, html, rtf, etc.) and emits ANY supported output format (xlsx, csv, json, md, html, etc.).\n' +
       'No other tool in the MCP space ingests legacy formats — pandas.read_excel only reads xlsx/xls; openpyxl is xlsx-only. xlsx_convert is the only "any-spreadsheet → LLM-readable" hosted endpoint.\n\n' +
       'USE WHEN: the user has a .xls / .xlsb / .ods / Numbers / .csv / Lotus / Quattro / dBASE file they want to read or convert. ' +
       'Output to text formats (csv/json/md/html) renders into the response body for the agent to read directly. Output to binary formats (xlsx/xlsb/etc.) returns bytes in `_meta.file_b64` for the npm client to save.\n\n' +
@@ -457,12 +440,10 @@ const TOOLS = [
   {
     name: 'xlsx_data_clean',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: AI-native data cleaning. Scans a workbook for the seven most common data-grime issues — NA variants (N/A, NA, null, -), merged-cell residue, type-coercion mistakes (numeric-as-text / date-as-serial / leading-zero stripped), trailing-row noise (footers / totals), header-row-not-first (preamble before headers), encoding glitches (UTF-8-as-CP1252 mojibake like Café), and duplicate column headers — and either flags them (diagnose mode) or applies deterministic fixes (execute mode).\n' +
-      'No other tool gives this in a single call: pandas does ad-hoc fixes inline; openpyxl is structure-only; pre-existing Python "clean" libraries are domain-specific. xlsx_data_clean is the only single-call clean pipeline with an explicit informer-not-enforcer contract: every fix surfaces as a Finding the caller can accept / reject / scope-override before the file is mutated.\n\n' +
-      'USE WHEN: an upstream pipeline produced an xlsx that\'s about to feed an LLM or downstream analysis and you want a one-pass scrub. Or you just got a "messy" export (financial reports with merged title banners, CRM exports with stripped zip codes, survey data with NA-variant noise) and need it normalized before reading. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: domain-specific transforms are needed (use a dedicated pipeline; this tool is general-purpose). Or for structural integrity checks (use xlsx_doctor). Or for upload/attached files.',
+      'AI-native data cleaning for a LOCAL .xlsx file. Scans for the seven most common data-grime issues — NA variants (N/A, NA, null, -), merged-cell residue, type-coercion mistakes (numeric-as-text / date-as-serial / leading-zero stripped), trailing-row noise (footers / totals), header-row-not-first (preamble before headers), encoding glitches (UTF-8-as-CP1252 mojibake), and duplicate column headers — and either flags them (diagnose mode) or applies deterministic fixes (execute mode).\n\n' +
+      'Informer-not-enforcer: every fix surfaces as a Finding the caller can accept / reject / scope-override before the file is mutated.\n\n' +
+      'USE WHEN: an upstream pipeline produced a messy xlsx that\'s about to feed an LLM or downstream analysis and you want a one-pass scrub.\n\n' +
+      'DO NOT USE WHEN: domain-specific transforms are needed (use a dedicated pipeline). Or for structural integrity checks (use xlsx_doctor). Or for upload/attached files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -519,8 +500,7 @@ const TOOLS = [
   {
     name: 'xlsx_validate',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: cross-engine consistency check on a LOCAL .xlsx file — runs the workbook through TWO independent renderers (@protobi/exceljs and @cj-tech-master/excelts) and reports cell-level divergences.\n' +
+      'cross-engine consistency check on a LOCAL .xlsx file — runs the workbook through TWO independent renderers (@protobi/exceljs and @cj-tech-master/excelts) and reports cell-level divergences.\n' +
       'No other tool can do this: pandas trusts cached values, openpyxl is single-engine, and Excel-itself disagrees with everything else on edge cases like LAMBDA, dynamic arrays, and timezone handling. xlsx_validate is the only way to know whether two engines agree on what your workbook says.\n\n' +
       'USE WHEN: the user is about to send the workbook downstream for analysis or as an authoritative source — pre-flight check. Or for audit / regression testing across engine versions. ' +
       'PAID — Bronze / Silver / Gold tier required.\n\n' +
@@ -537,8 +517,7 @@ const TOOLS = [
   {
     name: 'xlsx_data_validations',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every cell-level data validation rule (dropdowns, numeric/date bounds, text-length caps, custom formulas) defined in a workbook — the constraints that Excel enforces when a human types into the cell.\n' +
+      'list every cell-level data validation rule (dropdowns, numeric/date bounds, text-length caps, custom formulas) defined in a workbook — the constraints that Excel enforces when a human types into the cell.\n' +
       'No other tool can do this: pandas drops validations entirely on read; openpyxl exposes them but only on a per-cell loop; this surfaces them in one shot with target cells, formulae, error messages, and prompt text.\n\n' +
       'USE WHEN: auditing a form / data-entry workbook to know what inputs are legal. Or extracting a dropdown list for use elsewhere. Or generating fixtures that match the validation contract. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -556,8 +535,7 @@ const TOOLS = [
   {
     name: 'xlsx_hyperlinks',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every hyperlink in a workbook with its anchor cell, target URL/anchor, display text, tooltip, and a kind classifier (external / internal / mailto / unknown).\n' +
+      'list every hyperlink in a workbook with its anchor cell, target URL/anchor, display text, tooltip, and a kind classifier (external / internal / mailto / unknown).\n' +
       'No other tool can do this: pandas drops hyperlinks on read entirely; openpyxl gives raw access but does not classify or aggregate; this surfaces all links plus a per-kind tally for instant audit.\n\n' +
       'USE WHEN: security-auditing a workbook before opening it (what URLs does it point at?). Or extracting a reference list of URLs from a financial model / dashboard. Or finding mailto links for a contact-list workbook. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -575,8 +553,7 @@ const TOOLS = [
   {
     name: 'xlsx_topology',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: one-call workbook orientation. Returns sheets × dimensions × formulas × named ranges × tables × validations × hyperlinks × merges in one shot, plus feature flags (macros / external refs / pivots / LAMBDA / dynamic arrays).\n' +
+      'one-call workbook orientation. Returns sheets × dimensions × formulas × named ranges × tables × validations × hyperlinks × merges in one shot, plus feature flags (macros / external refs / pivots / LAMBDA / dynamic arrays).\n' +
       'No other tool can do this: pandas gives you a frame per sheet but no structure; openpyxl makes you fan out across 6+ object trees to learn the same thing; this is the "what is in this workbook?" call you make first to decide which other tool to call next.\n\n' +
       'USE WHEN: an agent has just been handed a workbook and needs to orient before drilling in. Or surveying many workbooks for triage / index. Or auditing whether a workbook is "interesting" (formulas? macros? external refs?). ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -593,8 +570,7 @@ const TOOLS = [
   {
     name: 'xlsx_conditional_formats',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every conditional formatting rule in a workbook — color scales, data bars, icon sets, formula-based highlights, top-N, duplicate / unique values, contains-text, time-period, above-average. Per rule: range, type, operator, formulae, priority, stopIfTrue.\n' +
+      'list every conditional formatting rule in a workbook — color scales, data bars, icon sets, formula-based highlights, top-N, duplicate / unique values, contains-text, time-period, above-average. Per rule: range, type, operator, formulae, priority, stopIfTrue.\n' +
       'No other tool can do this: pandas drops conditional formatting on read entirely; openpyxl exposes the raw CF objects but offers no rollup or classification. This surfaces every rule plus a per-type tally so an agent can answer "does this workbook use color scales?" without scanning every row.\n\n' +
       'USE WHEN: auditing a dashboard / financial model to know what visual cues a human would see. Or extracting business rules embedded as CF (e.g. "row turns red when col C > 1000" — the rule IS the spec). Or generating fixtures that match a workbook\'s CF semantics. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -612,8 +588,7 @@ const TOOLS = [
   {
     name: 'xlsx_comments',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every cell comment in a workbook — both legacy notes (yellow stickies, cell.note) AND modern threaded comments (multi-author conversations stored separately in the OOXML zip). Per entry: kind, sheet, cell, author, text, plus any reply thread.\n' +
+      'list every cell comment in a workbook — both legacy notes (yellow stickies, cell.note) AND modern threaded comments (multi-author conversations stored separately in the OOXML zip). Per entry: kind, sheet, cell, author, text, plus any reply thread.\n' +
       'No other tool can do this: pandas drops both comment systems on read entirely; openpyxl reads only legacy notes (not threaded comments). xlsx_comments reads both, maps personId → display name via xl/persons/person.xml, and folds reply chains into each root comment.\n\n' +
       'USE WHEN: extracting reviewer feedback / approval threads from a spreadsheet (this is where humans hide intent). Or auditing a workbook for hidden context the values themselves don\'t carry. Or building a "show me everywhere finance flagged something" report. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -631,12 +606,10 @@ const TOOLS = [
   {
     name: 'xlsx_doctor',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: ONE-CALL workbook health report. Scans for macros, external workbook references, hidden / veryHidden sheets, missing creator metadata, large embedded images, and surfaces interesting feature flags (LAMBDA, dynamic arrays, pivot cache, slicers, threaded comments). Findings ranked HIGH / MEDIUM / LOW. Plus quick_facts: sheet count, formulas, named ranges, merges, hyperlinks, validations, images, file size.\n' +
-      'No other tool does this aggregate triage in a single call. The "check this workbook" call agents should make BEFORE any other tool — single round trip, exhaustive, ranked output an LLM can read at a glance and decide what to do next (e.g. "macros detected, run xlsx_macros for details, then warn the user").\n\n' +
-      'USE WHEN: an agent has been handed an unknown workbook and needs to triage it before drilling in. Or pre-flighting a file that\'s about to be shared (catches "I\'m about to email this and didn\'t notice the macros" mistakes). Or building a file-quality dashboard across many workbooks. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: you already know what you\'re looking for (use the focused tool instead — xlsx_macros, xlsx_external_links, etc.). Or you only need data values (use xlsx_read).',
+      'ONE-CALL workbook health report for a LOCAL .xlsx file. Scans for macros, external workbook references, hidden / veryHidden sheets, missing creator metadata, large embedded images, and surfaces interesting feature flags (LAMBDA, dynamic arrays, pivot cache, slicers, threaded comments). Findings ranked HIGH / MEDIUM / LOW. Plus quick_facts: sheet count, formulas, named ranges, merges, hyperlinks, validations, images, file size.\n\n' +
+      'The "check this workbook" call agents should make BEFORE any other tool — single round trip, ranked output an LLM can read at a glance.\n\n' +
+      'USE WHEN: an agent has been handed an unknown workbook and needs to triage it before drilling in. Or pre-flighting a file before sharing.\n\n' +
+      'DO NOT USE WHEN: you already know what you\'re looking for (use the focused tool — xlsx_macros, xlsx_external_links, etc.). Or you only need data values (use xlsx_read).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -649,8 +622,7 @@ const TOOLS = [
   {
     name: 'xlsx_form_controls',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every form control (Check Box, Button, Drop-down, List Box, Option Button, Scroll Bar, Spinner, Label, Group Box) in a workbook with the linked cell, current value, dropdown source range, and min/max/step bounds where applicable.\n' +
+      'list every form control (Check Box, Button, Drop-down, List Box, Option Button, Scroll Bar, Spinner, Label, Group Box) in a workbook with the linked cell, current value, dropdown source range, and min/max/step bounds where applicable.\n' +
       'No other tool gives this in a single call: ExcelJS doesn\'t expose form controls; pandas drops them entirely; openpyxl support is partial. xlsx_form_controls reads xl/ctrlProps/ctrlProp*.xml directly + maps to sheets via the rel chain.\n\n' +
       'USE WHEN: documenting a survey workbook, scoring rubric, dashboard, or forms-as-spreadsheets template where the interactive UI carries semantic meaning. Or auditing a workbook to find which cells human users can change via a control vs. by direct typing. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -668,12 +640,9 @@ const TOOLS = [
   {
     name: 'xlsx_macros',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: inspect xlsm / xlsb workbooks for VBA macro presence, vbaProject.bin size, and likely module names (ThisWorkbook / Sheet<N> / Module<N> / Class<N> / UserForm<N> via heuristic UTF-16LE scan). Returns short safety advice for the LLM to relay to the user.\n' +
-      'No other tool gives this in a single call: pandas drops macros entirely; openpyxl exposes the raw vbaProject.bin bytes but no usable inspection. xlsx_macros gives the security-audit metadata an agent (or human) needs to decide "should I trust this file?" before opening.\n\n' +
-      'By DELIBERATE POLICY this tool does NOT extract or execute macro source code. Surfaces presence + module name candidates only.\n\n' +
-      'USE WHEN: receiving a macro-enabled workbook from an unknown sender and you want to know what to expect before opening. Or auditing a workbook population for "do any of these contain macros?" without sampling each. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'Inspect xlsm / xlsb workbooks for VBA macro presence, vbaProject.bin size, and likely module names (ThisWorkbook / Sheet<N> / Module<N> / Class<N> / UserForm<N> via heuristic UTF-16LE scan). Returns short safety advice the LLM should relay to the user.\n\n' +
+      'By DELIBERATE POLICY this tool does NOT extract or execute macro source code. Surfaces presence + module-name candidates only — security-audit metadata for "should I trust this file?" decisions.\n\n' +
+      'USE WHEN: receiving a macro-enabled workbook from an unknown sender and you want to know what to expect before opening. Or auditing many workbooks for "do any of these contain macros?" without sampling each.\n\n' +
       'DO NOT USE WHEN: you need to actually inspect / debug VBA source — open the file in Excel (Alt+F11) on a trusted machine.',
     inputSchema: {
       type: 'object',
@@ -687,8 +656,7 @@ const TOOLS = [
   {
     name: 'xlsx_merged_cells',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every merged-cell region with master-cell value, range, span dimensions, and kind heuristic ("header" / "horizontal" / "vertical" / "block"). Pandas reads merged cells by dropping the relationship — it sees one value in the master cell and three blanks alongside. xlsx_merged_cells is the layout-aware view: "A1:D1 is ONE cell that says Q4 2024" rather than four cells where three are mysteriously empty.\n' +
+      'list every merged-cell region with master-cell value, range, span dimensions, and kind heuristic ("header" / "horizontal" / "vertical" / "block"). Pandas reads merged cells by dropping the relationship — it sees one value in the master cell and three blanks alongside. xlsx_merged_cells is the layout-aware view: "A1:D1 is ONE cell that says Q4 2024" rather than four cells where three are mysteriously empty.\n' +
       'No other tool surfaces merges with master values rolled in: pandas drops merge metadata; openpyxl exposes ranges but not the master value alongside.\n\n' +
       'USE WHEN: parsing report templates, dashboards, or form workbooks where merges encode visual hierarchy (section titles, sub-headers, banner rows). Or auditing a workbook for accidental merges that distort downstream pandas reads. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -706,11 +674,9 @@ const TOOLS = [
   {
     name: 'xlsx_workbook_views',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: surface the UI state of a workbook — what a human sees when they open the file in Excel. Per sheet: visibility (visible / hidden / veryHidden), view state (normal / frozen / split / pageBreakPreview / pageLayout), zoom level, active cell + selection range, frozen pane breakdown (rows/cols frozen + top-left of scroll area), gridlines / row-col headers / ruler / RTL flags, tab color. Workbook level: which sheet is the active tab when Excel opens.\n' +
-      'No other tool surfaces this: pandas drops every bit of UI state; openpyxl exposes view objects but in deeply nested form. xlsx_workbook_views is the "when the user opens this file, what do they see?" rollup an LLM needs to reason about continuity (resume editing where they left off, notice a hidden sheet exists, etc.).\n\n' +
-      'USE WHEN: an agent has been handed a workbook mid-workflow and needs to know "where was the user last working?" (active cell, active tab, zoom). Or auditing for hidden / veryHidden sheets that often hide sensitive data. Or extracting frozen-pane configuration to recreate the same UX in a generated workbook. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'Surface the UI state of a LOCAL .xlsx file — what a human sees when they open it in Excel. Per sheet: visibility (visible / hidden / veryHidden), view state, zoom, active cell + selection, frozen-pane breakdown, gridlines / row-col headers / ruler / RTL flags, tab color. Workbook level: which sheet is active when Excel opens.\n\n' +
+      'The "when the user opens this file, what do they see?" rollup — useful when an agent needs to reason about UI continuity (resume editing, notice a hidden sheet, replicate frozen panes in a generated workbook).\n\n' +
+      'USE WHEN: handed a workbook mid-workflow and need "where was the user last working?" (active cell, tab, zoom). Or auditing for hidden / veryHidden sheets that often conceal sensitive data.\n\n' +
       'DO NOT USE WHEN: just reading values (use xlsx_read).',
     inputSchema: {
       type: 'object',
@@ -725,8 +691,7 @@ const TOOLS = [
   {
     name: 'xlsx_print_settings',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: surface "what would Excel print right now" per worksheet — print area, orientation, paper size (A4 / Letter / Legal / Tabloid / etc.), scale or fitToPage, margins, headers/footers split into Excel\'s L/C/R zones, print titles (rows / columns repeated on every page), manual page breaks, plus B&W / draft / centered flags.\n' +
+      'surface "what would Excel print right now" per worksheet — print area, orientation, paper size (A4 / Letter / Legal / Tabloid / etc.), scale or fitToPage, margins, headers/footers split into Excel\'s L/C/R zones, print titles (rows / columns repeated on every page), manual page breaks, plus B&W / draft / centered flags.\n' +
       'No other tool can do this rolled-up: pandas drops every bit of print configuration; openpyxl exposes it but in nested object form. xlsx_print_settings is the "if a human hits Cmd+P, what comes out?" answer.\n\n' +
       'USE WHEN: about to PDF / print a workbook and want to know what it\'ll look like before doing it. Or auditing a financial / regulatory report\'s print configuration (legal sometimes cares about page-1 headers). Or extracting the print-titles row a complex workbook uses for repeating headers. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -744,12 +709,10 @@ const TOOLS = [
   {
     name: 'xlsx_properties',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: surface the workbook\'s identity card. Core: creator, last_modified_by, created/modified/lastPrinted timestamps, title, subject, company, manager, keywords, category, description. Application: app name, app version, doc security label, hyperlink base. Custom: every user-defined Info > Properties entry (Department, ReviewedBy, ApprovalRequired, etc.) with type tag and value.\n' +
-      'No other tool gives you this rolled up: pandas drops document properties entirely; openpyxl exposes core props but in nested object form unsuitable for LLM consumption. Reads docProps/core.xml, docProps/app.xml, and docProps/custom.xml directly.\n\n' +
-      'USE WHEN: auditing a workbook for attribution ("who built this and when?"). Or stripping sensitive metadata before sharing externally (creator names, internal company names, manager email). Or extracting custom finance/legal flags ("ReviewedBy", "ApprovalRequired") that workflows pin to the file. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to MODIFY metadata (use xlsx_redact for sensitive-field stripping; xlsx_write does not write doc props).',
+      'Surface the workbook\'s identity card from a LOCAL .xlsx file. Core: creator, last_modified_by, created/modified/lastPrinted timestamps, title, subject, company, manager, keywords, category, description. Application: app name + version, doc security label, hyperlink base. Custom: every user-defined Info > Properties entry (Department, ReviewedBy, ApprovalRequired, etc.) with type tag and value.\n\n' +
+      'Reads docProps/core.xml, docProps/app.xml, and docProps/custom.xml directly — a surface pandas drops entirely.\n\n' +
+      'USE WHEN: auditing a workbook for attribution ("who built this and when?"). Or stripping sensitive metadata before sharing externally. Or extracting custom finance/legal flags ("ReviewedBy", "ApprovalRequired") that workflows pin to the file.\n\n' +
+      'DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to MODIFY metadata (use xlsx_redact for sensitive-field stripping).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -762,8 +725,7 @@ const TOOLS = [
   {
     name: 'xlsx_external_links',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every external workbook reference this file depends on — `=[Budget.xlsx]Sheet1!A1` style formulas. Per link: target path (decoded), classification (http / network share / absolute / relative), sheets pulled from the external workbook, count of cached cell values, and defined-name references.\n' +
+      'list every external workbook reference this file depends on — `=[Budget.xlsx]Sheet1!A1` style formulas. Per link: target path (decoded), classification (http / network share / absolute / relative), sheets pulled from the external workbook, count of cached cell values, and defined-name references.\n' +
       'No other tool can do this consistently: pandas, openpyxl, and ExcelJS all surface external links partially or inconsistently. xlsx_external_links reads xl/externalLinks/*.xml directly and warns when targets are absolute paths or network shares — those break the moment the workbook moves elsewhere.\n\n' +
       'USE WHEN: about to send a workbook somewhere and want to know if its formulas will break (broken external refs are a top-3 silent corruption mode in finance workflows). Or auditing for accidentally-leaked file paths to internal network shares. Or doing dependency analysis on a model. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -780,11 +742,9 @@ const TOOLS = [
   {
     name: 'xlsx_slicers_timelines',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every slicer (interactive filter button) and timeline (date-range filter visual) in a workbook with their captions, source bindings (table column or pivot table), and timeline granularity (years / quarters / months / days) plus the currently-selected date range.\n' +
-      'No other tool can do this: ExcelJS has NO API for slicers or timelines and silently drops both on every round-trip; pandas drops them entirely; openpyxl support is partial. xlsx_slicers_timelines reads the OOXML zip (xl/slicers/*, xl/slicerCaches/*, xl/timelines/*, xl/timelineCaches/*) directly.\n\n' +
-      'USE WHEN: documenting a dashboard so an LLM knows what filter UI a human sees. Or auditing whether a slicer\'s table-column binding still matches the underlying data after a refactor. Or extracting the date range a timeline currently filters on without screenshotting Excel. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'List every slicer (interactive filter button) and timeline (date-range filter visual) in a LOCAL .xlsx file with their captions, source bindings (table column or pivot table), and timeline granularity (years / quarters / months / days) plus the currently-selected date range.\n\n' +
+      'Reads the OOXML zip (xl/slicers/*, xl/slicerCaches/*, xl/timelines/*, xl/timelineCaches/*) directly — a surface ExcelJS silently drops on round-trip.\n\n' +
+      'USE WHEN: documenting a dashboard so an LLM knows what filter UI a human sees. Or auditing whether a slicer\'s binding still matches the underlying data after a refactor.\n\n' +
       'DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to APPLY a filter (use xlsx_filter — slicers/timelines are UI metadata, not data filters).',
     inputSchema: {
       type: 'object',
@@ -798,11 +758,9 @@ const TOOLS = [
   {
     name: 'xlsx_pivot_tables',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every PRE-EXISTING pivot table definition in a workbook (the ones an Excel user already built). Per pivot: sheet, name, location range, source range (or named-range / table reference), row / column / page fields, and data fields with their agg function (sum / count / average / max / min / product / stdDev / etc.).\n' +
-      'No other tool can do this: ExcelJS doesn\'t expose pivot tables; pandas drops them entirely; openpyxl reads them but in a deeply-nested object model unsuitable for LLM consumption. Distinct from `xlsx_pivot` which COMPUTES a fresh pivot from raw data — this tool surfaces the existing pivot CONTRACT so an agent can answer "what does PivotTable3 on the Summary sheet actually compute?".\n\n' +
-      'USE WHEN: documenting a financial model that uses pivot tables. Or auditing whether a pivot still points at the right source range after a data-table refactor. Or answering "which sheet aggregates Sales by Region?" without re-deriving it. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'List every PRE-EXISTING pivot table definition in a LOCAL .xlsx file (the ones an Excel user already built). Per pivot: sheet, name, location range, source range (or named-range / table reference), row / column / page fields, and data fields with their agg function (sum / count / average / max / min / product / stdDev / etc.).\n\n' +
+      'Distinct from `xlsx_pivot` which COMPUTES a fresh pivot from raw data — this tool surfaces the existing pivot CONTRACT so an agent can answer "what does PivotTable3 on the Summary sheet actually compute?".\n\n' +
+      'USE WHEN: documenting a financial model that uses pivot tables. Or auditing whether a pivot still points at the right source range after a data refactor. Or answering "which sheet aggregates Sales by Region?" without re-deriving it.\n\n' +
       'DO NOT USE WHEN: you want to COMPUTE a fresh pivot from raw data (use xlsx_pivot). Or you only need cell values (use xlsx_read).',
     inputSchema: {
       type: 'object',
@@ -817,12 +775,10 @@ const TOOLS = [
   {
     name: 'xlsx_images',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every embedded image in a workbook with format (png / jpg / gif / svg / bmp / tiff / emf / wmf), size in bytes, sheet attribution, and anchor cell range (the cells the image floats over). Reads xl/media/* + xl/drawings/* directly.\n' +
-      'No other tool can do this in one call: pandas drops images entirely; openpyxl reads images but doesn\'t roll them up by sheet/format/size or surface anchor cell refs in human-readable form. xlsx_images surfaces "Sheet1 has a 4 KB PNG anchored at B2:D6" — the exact thing an LLM needs to know whether the workbook ships with branding / charts-as-images / signatures.\n\n' +
-      'USE WHEN: cataloging the visual assets in a financial / operational workbook. Or auditing a workbook for embedded images that need to be replaced (logos changed, signatures rotated). Or fingerprinting a template by its image inventory. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: you want the image PIXELS (this surfaces metadata, not bytes — fetching the bytes would inflate the response well beyond LLM context budgets). Or you only need cell values (use xlsx_read).',
+      'List every embedded image in a LOCAL .xlsx file with format (png / jpg / gif / svg / bmp / tiff / emf / wmf), size in bytes, sheet attribution, and anchor cell range (the cells the image floats over). Reads xl/media/* + xl/drawings/* directly.\n\n' +
+      'Surfaces "Sheet1 has a 4 KB PNG anchored at B2:D6" — what an LLM needs to know whether the workbook ships with branding / charts-as-images / signatures.\n\n' +
+      'USE WHEN: cataloging visual assets. Or auditing a workbook for embedded images that need to be replaced (logos, signatures). Or fingerprinting a template by its image inventory.\n\n' +
+      'DO NOT USE WHEN: you want the image PIXELS (this surfaces metadata, not bytes). Or you only need cell values (use xlsx_read).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -836,12 +792,10 @@ const TOOLS = [
   {
     name: 'xlsx_charts',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: list every chart in a workbook with type (bar / line / pie / scatter / area / doughnut / radar / stock / surface / bubble), title, axis titles, and per-series formula refs (the cell ranges the chart pulls from). Sheet attribution via the OOXML drawing rel chain.\n' +
-      'No other tool can do this: ExcelJS doesn\'t expose charts at all (read or write); pandas drops them entirely; openpyxl reads charts but in a deeply-nested object form unsuitable for LLM consumption. xlsx_charts gives you the chart contract — "Sheet2 has a bar chart titled Q4 Revenue plotting Sheet1!B2:B10 against Sheet1!A2:A10" — without rendering anything.\n\n' +
-      'USE WHEN: documenting a financial model / dashboard for an LLM that needs to know "what does this workbook visualize, and from which cells?". Or auditing a workbook for chart-data drift after a refactor (chart still points at old range?). ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: you want to RENDER the chart as an image (this tool returns the chart spec, not pixels). Or you only need cell values (use xlsx_read).',
+      'List every chart in a LOCAL .xlsx file with type (bar / line / pie / scatter / area / doughnut / radar / stock / surface / bubble), title, axis titles, and per-series formula refs (the cell ranges the chart pulls from). Sheet attribution via the OOXML drawing rel chain.\n\n' +
+      'Gives you the chart contract — "Sheet2 has a bar chart titled Q4 Revenue plotting Sheet1!B2:B10 against Sheet1!A2:A10" — without rendering anything.\n\n' +
+      'USE WHEN: documenting a financial model / dashboard so an LLM knows "what does this visualize, from which cells?". Or auditing for chart-data drift after a refactor.\n\n' +
+      'DO NOT USE WHEN: you want to RENDER the chart as an image (this returns the spec, not pixels). Or you only need cell values (use xlsx_read).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -855,12 +809,10 @@ const TOOLS = [
   {
     name: 'xlsx_protection',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: surface every protection setting in a workbook so an agent knows what it can and cannot edit. Workbook-level (lockStructure, lockWindows), per-sheet (protected? password? hidden state?), per-action allow/block list (formatCells, sort, insertRows, pivotTables, etc.), and per-cell unlocked / hidden samples — these are the cells a human would actually be allowed to type into when the sheet is otherwise read-only.\n' +
-      'No other tool can do this: pandas drops protection metadata entirely; openpyxl exposes the bool but no normalization. xlsx_protection reads sheetProtection action attrs directly from the OOXML zip (workaround for ExcelJS stripping them on round-trip).\n\n' +
-      'USE WHEN: an agent is about to suggest edits to a workbook and you want to fail fast on cells / sheets the user can\'t change anyway. Or auditing a "submitted form" workbook to see which inputs the form-author intended to be fillable. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to BREAK protection (this tool surfaces what\'s locked; it does not unlock).',
+      'Surface every protection setting in a LOCAL .xlsx file so an agent knows what it can and cannot edit. Workbook-level (lockStructure, lockWindows), per-sheet (protected? password? hidden state?), per-action allow/block list (formatCells, sort, insertRows, pivotTables, etc.), and per-cell unlocked / hidden samples — these are the cells a human would actually be allowed to type into when the sheet is otherwise read-only.\n\n' +
+      'Reads sheetProtection action attrs directly from the OOXML zip (workaround for ExcelJS stripping them on round-trip).\n\n' +
+      'USE WHEN: an agent is about to suggest edits and you want to fail fast on cells / sheets the user can\'t change anyway. Or auditing a "submitted form" workbook to see which inputs the author intended fillable.\n\n' +
+      'DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to BREAK protection (this surfaces what\'s locked; it does not unlock).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -874,8 +826,7 @@ const TOOLS = [
   {
     name: 'xlsx_styles',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: surface cell formatting (number formats, fonts, fills, alignment) so an agent knows what a cell LOOKS like, not just its raw value. Default mode: per-sheet rollup of top-N number formats / fonts / fills with counts. Detailed mode (opt-in, capped at 1000 cells): per-cell breakdown for narrow queries.\n' +
+      'surface cell formatting (number formats, fonts, fills, alignment) so an agent knows what a cell LOOKS like, not just its raw value. Default mode: per-sheet rollup of top-N number formats / fonts / fills with counts. Detailed mode (opt-in, capped at 1000 cells): per-cell breakdown for narrow queries.\n' +
       'No other tool can do this with this fidelity: pandas drops styles on read entirely. The single most valuable slice is number formats — pandas hands an LLM "45292" and the cell rendered as "2024-01-01" because format was "yyyy-mm-dd". xlsx_styles is what makes that recoverable.\n\n' +
       'USE WHEN: an LLM is about to interpret raw numbers (date serials, currency, percents, scientific notation) and you want the format hint that tells it what those numbers MEAN to a human. Or auditing a dashboard\'s typography. Or fingerprinting a template. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
@@ -894,8 +845,7 @@ const TOOLS = [
   {
     name: 'xlsx_post_slack',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message.\n' +
+      'upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message.\n' +
       'Token intake: set SLACK_BOT_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
       'Alternatively pass slack_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
       'Posts via Slack\'s 3-step external upload flow (files.getUploadURLExternal → upload → files.completeUploadExternal), which is the only sanctioned path as of 2024+.\n\n' +
@@ -918,14 +868,10 @@ const TOOLS = [
   {
     name: 'xlsx_post_teams',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message.\n' +
-      'Token intake: set TEAMS_GRAPH_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
-      'Alternatively pass graph_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
-      'Uses Microsoft Graph\'s 4-step flow: locate the channel\'s filesFolder driveItem, create an upload session, upload the bytes, then post a chatMessage with the file as an inline attachment.\n\n' +
-      'USE WHEN: the user asks "post this workbook to my Teams channel," "share this with the team in Teams," or any other outbound-file-to-Teams request. The agent has just produced or modified a workbook and wants to deliver it to a Microsoft Teams channel. ' +
-      'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when no Microsoft Graph token is available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
+      'Upload a local .xlsx file to a Microsoft Teams channel as a file attachment, with an optional accompanying message.\n\n' +
+      'Token intake: set TEAMS_GRAPH_TOKEN in the environment (recommended — keeps the token out of conversation logs). Alternatively pass graph_token as a tool argument (legacy; token will appear in MCP history). Uses Microsoft Graph\'s upload-session + chatMessage flow.\n\n' +
+      'USE WHEN: the user asks "post this workbook to my Teams channel" or any outbound-file-to-Teams request after producing or modifying a workbook.\n\n' +
+      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when no Microsoft Graph token is available — the user needs an Entra ID app with Files.ReadWrite.All + ChannelMessage.Send scopes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -943,11 +889,10 @@ const TOOLS = [
   {
     name: 'xlsx_stamp',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: sign a workbook with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn\'t been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'Sign a LOCAL .xlsx file with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn\'t been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n\n' +
       'The caller supplies the `checks` array (e.g., from a supervisor review): list of named tests, each with passed/failed/skipped status. Verifiers see the individual check results, not a single good/bad opinion.\n\n' +
-      'USE WHEN: the agent has just produced or reviewed a workbook and wants to attach provable provenance + check results that travel with the file. The recipient can later verify the stamp via xlsx_verify_stamp to confirm the file hasn\'t been modified and to see the original check results.\n\n' +
-      'DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams). Or when there are no real checks to attest to (an empty checks array is allowed and means "we ran zero checks" — but the stamp\'s value is in the checks it records).',
+      'USE WHEN: an agent has just produced or reviewed a workbook and wants to attach provable provenance + check results that travel with the file. Recipients verify via xlsx_verify_stamp.\n\n' +
+      'DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -977,8 +922,7 @@ const TOOLS = [
   {
     name: 'xlsx_verify_stamp',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: verify a workbook\'s embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.\n' +
+      'verify a workbook\'s embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.\n' +
       'A workbook can fail verification three ways: (1) no stamp present (file was never stamped, or the stamp was stripped); (2) signature_valid=false (someone modified the claims after signing, or signed with a different key); (3) hash_matches=false (someone modified the workbook bytes after signing). Each is a distinct trust signal.\n\n' +
       'USE WHEN: the agent (or a downstream verifier) needs to confirm a workbook hasn\'t been tampered with since it was signed, OR needs to surface the original check results that were attested to. Common scenario: incoming workbook from a counterparty, agent runs verify before trusting any of its values.',
     inputSchema: {
@@ -993,11 +937,10 @@ const TOOLS = [
   {
     name: 'xlsx_receipt',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: attach an AI-generation receipt to a workbook — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by THIS agent, at THIS time, against THESE inputs." Returns the receipted workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
-      'Honesty boundary (load-bearing): the server signs the CALLER-DECLARED `agent.name` — it does NOT verify the caller actually IS that agent. The signature proves "this server signed these strings at this time," not "this came from claude-sonnet-4-6." Caller is responsible for honest declaration. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope.\n\n' +
-      'USE WHEN: an AI agent (Claude, custom SDK agent, automated pipeline) generates a workbook and the recipient wants verifiable provenance — "what produced this file, when, against what." Or chaining attestations across a multi-step pipeline (each step adds its own receipt under different agent.name).\n\n' +
-      'DO NOT USE WHEN: the workbook was human-authored (use xlsx_stamp — Stamp attests to check results, Receipt attests to generation context). Or when the use case demands cryptographically-bound identity (v1.1+).',
+      'Attach an AI-generation receipt to a LOCAL .xlsx file — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by THIS agent, at THIS time, against THESE inputs." Returns the receipted workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n\n' +
+      'Honesty boundary (load-bearing): the server signs the CALLER-DECLARED `agent.name` — it does NOT verify the caller actually IS that agent. The signature proves "this server signed these strings at this time," not "this came from claude-sonnet-4-6." Caller is responsible for honest declaration. Cryptographic identity binding is v1.1+ scope.\n\n' +
+      'USE WHEN: an AI agent generates a workbook and the recipient wants verifiable provenance — "what produced this file, when, against what." Or chaining attestations across a multi-step pipeline.\n\n' +
+      'DO NOT USE WHEN: the workbook was human-authored (use xlsx_stamp — Stamp attests to check results, Receipt attests to generation context).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1033,8 +976,7 @@ const TOOLS = [
   {
     name: 'xlsx_verify_receipt',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: verify a workbook\'s embedded AI-generation receipt. Returns whether the signature is valid, whether the recomputed content hash matches the hash IN the receipt, and the full caller-declared claims (agent identity, generation timestamp, source-file hashes, prompt hash, MCP tools called, description).\n' +
+      'verify a workbook\'s embedded AI-generation receipt. Returns whether the signature is valid, whether the recomputed content hash matches the hash IN the receipt, and the full caller-declared claims (agent identity, generation timestamp, source-file hashes, prompt hash, MCP tools called, description).\n' +
       'A workbook can fail verification three ways: (1) no receipt present (never receipted, or receipt was stripped); (2) signature_valid=false (claims modified after signing); (3) hash_matches=false (workbook bytes modified after receipt was generated). Honesty: a valid receipt proves the SERVER signed the caller-DECLARED agent string — not that the agent IS that.\n\n' +
       'USE WHEN: a workbook arrives claiming AI provenance and the user wants to verify it. Or auditing a corpus of workbooks to find ones with broken receipts (likely-tampered) or no receipts at all.',
     inputSchema: {
@@ -1049,8 +991,7 @@ const TOOLS = [
   {
     name: 'xlsx_healer_diagnose',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: produce a structured diagnostic report of external references that are broken or at risk in a workbook. Returns five classes of finding: (1) external-workbook references that can\'t resolve, (2) defined-name external refs, (3) Power Query connections with embedded credentials, (4) #REF! propagation maps from upstream breakage, (5) multi-hop chains (workbook → workbook → workbook). Findings carry reference_id keys that downstream cure operations key on.\n\n' +
+      'produce a structured diagnostic report of external references that are broken or at risk in a workbook. Returns five classes of finding: (1) external-workbook references that can\'t resolve, (2) defined-name external refs, (3) Power Query connections with embedded credentials, (4) #REF! propagation maps from upstream breakage, (5) multi-hop chains (workbook → workbook → workbook). Findings carry reference_id keys that downstream cure operations key on.\n\n' +
       'USE WHEN: a workbook shows #REF! errors, an agent moves a file and refs need rewriting, a customer reports "the workbook stopped working after we reorganized SharePoint", or auditing a corpus for hidden external-link breakage before sharing.\n\n' +
       'DO NOT USE WHEN: the user wants the cleaning/normalization surface (use xlsx_data_clean — different concern). Or when there is no .xlsx source path (Healer reads the source bytes, doesn\'t reconstruct from a structured spec).',
     inputSchema: {
@@ -1065,10 +1006,9 @@ const TOOLS = [
   {
     name: 'xlsx_healer_cure',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: apply ONE specific cure operation against a diagnosed workbook. Each operation targets a specific failure mode: rename_move (rewrite ref paths), pattern_bulk (regex-style ref rewrites), source_deleted_freeze (replace broken refs with cached values), source_deleted_redirect (point at a replacement file), source_deleted_localize (snapshot full external source into a local copy), permission_denied (strip credentials), structure_changed (rewrite formulas for moved cells), format_change (re-link after extension change), make_standalone (fully dereference all externals). Returns the cured workbook bytes + a receipt naming exactly what changed.\n\n' +
-      'USE WHEN: a diagnostic report (xlsx_healer_diagnose) named a specific operation as the recommended fix and the user confirmed it; or running a known recipe across a folder of files; or restoring a workbook whose source moved by a known prefix.\n\n' +
-      'DO NOT USE WHEN: the failure mode isn\'t one of the supported operations (use xlsx_healer_intent for goal-shaped fixes). Or when diagnose hasn\'t been run yet on the file (cures need diagnose-emitted reference_ids).',
+      'Apply ONE specific cure operation against a diagnosed workbook. Operations: rename_move (rewrite ref paths), pattern_bulk (regex-style ref rewrites), source_deleted_freeze (replace broken refs with cached values), source_deleted_redirect (point at a replacement file), source_deleted_localize (snapshot external source into a local copy), permission_denied (strip credentials), structure_changed (rewrite formulas for moved cells), format_change (re-link after extension change), make_standalone (fully dereference all externals). Returns cured workbook bytes + receipt.\n\n' +
+      'USE WHEN: a diagnostic report (xlsx_healer_diagnose) named a specific operation as the recommended fix; or restoring a workbook whose source moved by a known prefix.\n\n' +
+      'DO NOT USE WHEN: the failure mode isn\'t a supported operation (use xlsx_healer_intent for goal-shaped fixes). Or when diagnose hasn\'t been run (cures need diagnose-emitted reference_ids).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1112,8 +1052,7 @@ const TOOLS = [
   {
     name: 'xlsx_healer_simulate',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: simulate recipient-side accessibility of a workbook\'s external references. Given a list of paths the recipient CAN see (`accessible_paths`), returns which references will still resolve at the recipient end and which will break (and why). Read-only; produces no output workbook.\n\n' +
+      'simulate recipient-side accessibility of a workbook\'s external references. Given a list of paths the recipient CAN see (`accessible_paths`), returns which references will still resolve at the recipient end and which will break (and why). Read-only; produces no output workbook.\n\n' +
       'USE WHEN: an agent or user wants to know "will this workbook work when I send it to <person>?" before sharing — e.g., before posting to Slack, attaching to email, or sharing a OneDrive link. Or auditing a workbook against a known recipient-accessible-paths inventory.\n\n' +
       'DO NOT USE WHEN: the user wants to FIX the breakage (use xlsx_healer_cure or xlsx_healer_intent). Or when the recipient is the sender themselves (no path discrepancy to simulate).',
     inputSchema: {
@@ -1133,10 +1072,9 @@ const TOOLS = [
   {
     name: 'xlsx_healer_intent',
     description:
-      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: goal-driven healing. Caller declares an INTENT (`make-it-work`, `make-standalone`, or `migrate`) instead of a specific cure operation; Healer plans the operation sequence + applies it. make-it-work: minimum surgery to clear errors. make-standalone: fully de-externalize the workbook (snapshot every external dep). migrate: rewrite all references against a from/to prefix pair. Returns the planned operations, the cured bytes, and an unactionable list for refs that couldn\'t be auto-resolved.\n\n' +
-      'USE WHEN: the user describes the goal in plain English ("just make this work for the recipient" / "send a fully self-contained version" / "we moved the share root, update the refs"). Or when multiple cure operations need to compose and the orchestration is non-trivial.\n\n' +
-      'DO NOT USE WHEN: the user has already chosen a specific cure operation (use xlsx_healer_cure directly — avoids the planning overhead). Or when no diagnostic has been run on the workbook yet (intent uses the diagnostic surface internally; running diagnose first surfaces what intent will work with).',
+      'Goal-driven healing. Caller declares an INTENT (`make-it-work`, `make-standalone`, or `migrate`) instead of a specific cure operation; Healer plans the operation sequence + applies it. make-it-work: minimum surgery to clear errors. make-standalone: fully de-externalize (snapshot every external dep). migrate: rewrite all references against a from/to prefix pair. Returns the planned operations, cured bytes, and an unactionable list.\n\n' +
+      'USE WHEN: the user describes the goal in plain English ("just make this work for the recipient" / "send a self-contained version" / "we moved the share root, update the refs"). Or when multiple cure operations need to compose.\n\n' +
+      'DO NOT USE WHEN: the user has chosen a specific cure operation (use xlsx_healer_cure directly). Or when no diagnostic has been run on the workbook yet.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1168,6 +1106,68 @@ const TOOLS = [
       required: ['file_path', 'intent'],
     },
   },
+  {
+    name: 'xlsx_read_handle',
+    description:
+      'read a workbook that has already been uploaded to the server via the chunked upload flow, by its server-side cache handle, WITHOUT re-transferring the bytes. Returns the same shape as xlsx_read (text / json / markdown) but skips the file_b64 round-trip.\n\n' +
+      'USE WHEN: the workbook has already been chunked + finalized into the server-side workbook cache (a `workbook_handle` was returned from the finalize call) and you want to read it again — e.g., a multi-step session where the same large workbook is queried repeatedly. Avoids re-uploading the bytes on every call.\n\n' +
+      'DO NOT USE WHEN: you have a local file path and no prior upload (use xlsx_read — it handles the file_b64 transport for you). Handles expire when the cache TTL elapses; the call returns a clear "not found / expired" error in that case.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workbook_handle: {
+          type: 'string',
+          description: 'Server-side cache handle returned by the chunked-upload finalize call. 1-128 chars.',
+          minLength: 1,
+          maxLength: 128,
+        },
+        sheet: { type: 'string', description: 'Optional: restrict the read to a single sheet by name.' },
+        format: {
+          type: 'string',
+          enum: ['md', 'json'],
+          description: 'Output format. Defaults to md.',
+        },
+      },
+      required: ['workbook_handle'],
+    },
+  },
+  {
+    name: 'xlsx_session_set_validations',
+    description:
+      'configure per-session data-validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns, enforce enum values on a category column, range-bound numeric inputs). Stateful — affects this session only.\n\n' +
+      'USE WHEN: the workflow has multiple write/clean steps in sequence and you want consistent server-side validation across them without restating the rules on every call. Or when validating user-supplied data against a known schema you want enforced for the rest of the session.\n\n' +
+      'DO NOT USE WHEN: you only have a single call to make (just include the validation logic in that call). Or when you do not have a `session_id` (sessions are returned from the session-create surface; this tool is a no-op without one).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Session identifier returned by the session-create surface. 16-128 chars.',
+          minLength: 16,
+          maxLength: 128,
+        },
+        validations: {
+          type: 'array',
+          description: 'List of validation rules to apply. Each rule names a sheet, a cell ref (e.g., "A1:A100"), and a type (whole|decimal|list|date|time|textLength|custom).',
+          minItems: 1,
+          maxItems: 5000,
+          items: {
+            type: 'object',
+            properties: {
+              sheet: { type: 'string', description: 'Target sheet name.' },
+              ref: { type: 'string', description: 'A1-style cell range the rule applies to.' },
+              type: {
+                type: 'string',
+                description: 'Validation type. Server-side enum: whole, decimal, list, date, time, textLength, custom.',
+              },
+            },
+            required: ['sheet', 'ref', 'type'],
+          },
+        },
+      },
+      required: ['session_id', 'validations'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1738,6 +1738,27 @@ async function dispatchTool(name, args) {
     return applyFileB64(result, args.out_path);
   }
 
+  // Handle-based read (no file_b64; the bytes are already in the server
+  // cache from a prior chunked-upload finalize). Body mirrors the server
+  // schema in routes/xlsx-read-handle.ts.
+  if (name === 'xlsx_read_handle') {
+    const options = {};
+    if (args.sheet !== undefined) options.sheet = args.sheet;
+    if (args.format !== undefined) options.format = args.format;
+    const body = { workbook_handle: args.workbook_handle };
+    if (Object.keys(options).length > 0) body.options = options;
+    return callTool('xlsx_read_handle', body);
+  }
+
+  // Session-state write — no file bytes, just session_id + validation rules.
+  // Body mirrors the server schema in routes/xlsx-session-set-validations.ts.
+  if (name === 'xlsx_session_set_validations') {
+    return callTool('xlsx_session_set_validations', {
+      session_id: args.session_id,
+      validations: args.validations,
+    });
+  }
+
   // All other tools (list_sheets, schema, hyperlinks, conditional_formats,
   // styles, etc.) — single-file relay. Forward any common option keys the
   // routes accept so we don't silently drop them. New keys added here as
@@ -1758,46 +1779,56 @@ async function dispatchTool(name, args) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  await ensureRegistered();
+  // Swallow EPIPE on the transport. When the client disconnects while a
+  // background catalog upgrade is still in flight, sendToolListChanged
+  // writes to a closed pipe and Node raises EPIPE asynchronously on the
+  // Socket — our awaited try/catch around sendToolListChanged never sees
+  // it. Without this guard, a client unplug after the upgrade settles
+  // crashes the process with an unhandled Socket 'error' event.
+  //
+  // stdout is the MCP transport: EPIPE there means the client is gone,
+  // exit cleanly. stderr is the log sink: an EPIPE on stderr (parent
+  // closed its log pipe) is NOT a transport failure and must not take
+  // the server down.
+  process.stdout.on('error', (err) => {
+    if (err && err.code === 'EPIPE') {
+      process.exit(0);
+    }
+    // Anything else on the transport stream is a real failure (e.g.
+    // ERR_STREAM_DESTROYED) — rethrow so it surfaces as uncaughtException
+    // instead of being silently swallowed.
+    throw err;
+  });
+  process.stderr.on('error', (err) => {
+    // Silence EPIPE on stderr; rethrow anything else so we don't hide
+    // genuine logging-layer bugs.
+    if (!err || err.code !== 'EPIPE') throw err;
+  });
 
-  // Dynamic tool catalog: query the hosted API once at startup so new
-  // server-side tools appear without re-publishing this npm package.
-  // resolveCatalog returns the baked-in TOOLS as last-resort fallback so
-  // we never fail-open on a transient network blip. See lib/discover.js.
+  // `initialize` MUST respond from local state — never block on the network.
+  // Under Claude Desktop's bundled Node 24.x runtime, the registration POST
+  // and the catalog GET can hang indefinitely (Happy-Eyeballs / IPv6 dial
+  // edge cases inside Electron), and the client gives up at 60s. The whole
+  // MCP attach dies before tools/list is even called.
   //
-  // Hard timeout (8s) on top of any timeout inside resolveCatalog so that
-  // a network call which hangs forever (DNS sinkhole, TCP black hole, slow-
-  // loris-style stalled response) cannot block MCP server startup
-  // indefinitely. Pre-Friday-external CRITICAL per the Tier-1 audit.
-  const CATALOG_FETCH_TIMEOUT_MS = 8000;
-  let catalog;
-  try {
-    catalog = await Promise.race([
-      resolveCatalog(TOOLS),
-      new Promise((_, reject) =>
-        setTimeout(
-          () => reject(new Error(`catalog fetch timed out after ${CATALOG_FETCH_TIMEOUT_MS}ms`)),
-          CATALOG_FETCH_TIMEOUT_MS
-        )
-      ),
-    ]);
-  } catch (_) {
-    catalog = { tools: TOOLS, source: 'static-fallback' };
-  }
-  // Surface catalog source so operators can tell server vs cache vs static
-  // when an MCP session looks "off" (e.g., a tool missing because the remote
-  // /api/v1/tools/list 404'd and we silently fell back to the stale baked-in
-  // set). Stderr only — stdout is the MCP transport.
-  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=${catalog.source} count=${Array.isArray(catalog.tools) ? catalog.tools.length : 0}\n`);
-  // Overlay MCP annotations (title / readOnlyHint / destructiveHint) so
-  // they flow through to clients regardless of catalog source. The remote
-  // /api/v1/tools/list returns minimal entries today; this is what
-  // restores the annotations the wire format would otherwise drop.
-  const liveTools = applyAnnotations(Array.isArray(catalog.tools) ? catalog.tools : []);
+  // Shape: connect transport FIRST with the bundled TOOLS as the floor.
+  // Then background-upgrade registration + catalog with bounded timeouts,
+  // and fire notifications/tools/list_changed once the live catalog lands.
+  // The bundled set already covers every tool the user reaches in normal
+  // flows; the upgrade is additive.
+  // sanitizeForMcp guarantees every tool the server emits has a valid
+  // inputSchema + description — without it Claude Desktop silently drops
+  // tools that lack inputSchema, which is the exact symptom in SPM P0
+  // 2026-06-05 (mcp-toolslist-missing-inputschema). For the bundled
+  // catalog this is a no-op (every TOOLS entry already has full fields);
+  // for the upgraded catalog it's the floor that keeps stub server
+  // entries registerable.
+  let liveTools = sanitizeForMcp(applyAnnotations(TOOLS));
+  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=bundled count=${liveTools.length}\n`);
 
   const server = new Server(
     { name: 'xlsx-for-ai', version: require('./package.json').version },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: { listChanged: true } } }
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: liveTools }));
@@ -1841,6 +1872,88 @@ async function main() {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Background-upgrade: registration + dynamic catalog. Bounded so a
+  // hung network never wastes resources; failure is non-fatal because
+  // the bundled catalog already serves tools/list. Detached on purpose
+  // — we do not await this; main() returns and the upgrade lands when
+  // it lands.
+  upgradeCatalogInBackground(server, (next) => {
+    liveTools = next;
+  });
+}
+
+async function withTimeout(promise, ms, label) {
+  // Promise.race with a setTimeout-rejecting promise leaks unhandled
+  // rejections in two directions:
+  //   (a) Main wins — the timer still fires later and its branch
+  //       rejects with nobody awaiting it. clearTimeout in finally
+  //       eliminates this.
+  //   (b) Timer wins — the original promise can still reject later
+  //       (the underlying fetch eventually errors out long after we
+  //       gave up). Attaching a no-op catch ensures that late
+  //       rejection is consumed instead of crashing the MCP server
+  //       minutes after startup.
+  // The (b) case is the SPM P0 surface: the bundled-Node-24 dial
+  // can stall, time out, and then much later reject with EAI_AGAIN
+  // or a TLS error — by then nobody is listening.
+  promise.catch(() => {});
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${ms}ms`)),
+          ms
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function upgradeCatalogInBackground(server, swap) {
+  const REGISTRATION_TIMEOUT_MS = 10_000;
+  const CATALOG_TIMEOUT_MS = 8_000;
+
+  try {
+    await withTimeout(ensureRegistered(), REGISTRATION_TIMEOUT_MS, 'registration');
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai-mcp: registration deferred (${err.message})\n`);
+  }
+
+  let catalog;
+  try {
+    catalog = await withTimeout(resolveCatalog(TOOLS), CATALOG_TIMEOUT_MS, 'catalog fetch');
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai-mcp: catalog upgrade skipped (${err.message})\n`);
+    return;
+  }
+
+  if (!catalog || !Array.isArray(catalog.tools)) {
+    return;
+  }
+  // No upgrade to apply when discover.js fell back to the baked-in set
+  // (source=static): the list is identical to what initialize already
+  // returned, so a list_changed notification would be wire noise.
+  if (catalog.source === 'static') {
+    process.stderr.write(`xlsx-for-ai-mcp: catalog upgrade unavailable (source=static) — staying on bundled\n`);
+    return;
+  }
+
+  const upgraded = sanitizeForMcp(applyAnnotations(catalog.tools));
+  swap(upgraded);
+  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=${catalog.source} count=${upgraded.length}\n`);
+
+  try {
+    await server.sendToolListChanged();
+  } catch (_) {
+    // Transport may already be torn down (client disconnected before the
+    // upgrade landed). Non-fatal — next attach starts with the bundled
+    // catalog and retries the upgrade.
+  }
 }
 
 // Guard: don't auto-start when required by tests

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "3.0.0",
+  "version": "3.0.4",
   "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": {