pandas-style df.groupby([cols]).agg({col: func}) on a LOCAL .xlsx file. funcs: sum / mean / min / max / count / count_distinct. Type-aware: numeric aggregations skip non-numeric values cleanly instead of pandas' silent NaN promotion.

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.

DO NOT USE WHEN: the user wants to see individual rows (use xlsx_filter). Or for a 2D pivot (use xlsx_pivot).

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.

Gives you the chart contract — "Sheet2 has a bar chart titled Q4 Revenue plotting Sheet1!B2:B10 against Sheet1!A2:A10" — without rendering anything.

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.

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).

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. 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.

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.

DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to ADD comments to a workbook (xlsx_write does not write comments).

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. 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.

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.

DO NOT USE WHEN: you only care about cell values (use xlsx_read). Or you want to re-apply CF rules to a NEW workbook (xlsx_write does not write CF rules).

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.). 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.

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.

DO NOT USE WHEN: the input is already xlsx and you want to read it (use xlsx_read). 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).

Informer-not-enforcer: every fix surfaces as a Finding the caller can accept / reject / scope-override before the file is mutated.

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.

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.

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. 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.

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.

DO NOT USE WHEN: just trying to read values (use xlsx_read). Or trying to enforce validations on write (xlsx_write does not write validations).

pandas-style df.describe() per column — count, nulls, unique, min/max/mean/std for numerics, dtype with purity score. Unlike pandas.read_excel followed by df.describe(), this does not silently flatten merged cells or drop named ranges.

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.

DO NOT USE WHEN: the user uploaded a file via paperclip/attach (built-in skill). Or for in-memory data the agent already holds.

compute a semantic diff between two LOCAL .xlsx files — cell-level deltas, formula changes, added/removed rows. Output is byte-deterministic — calling twice with the same inputs returns identical text + diff_hash in _meta. Use that hash for caching/idempotence.

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.

DO NOT USE WHEN: either file came from an upload/attachment rather than a local path.

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.

The "check this workbook" call agents should make BEFORE any other tool — single round trip, ranked output an LLM can read at a glance.

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.

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).

evaluate Excel formulas against a LOCAL .xlsx file via HyperFormula. xlwings-style. 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.

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.

DO NOT USE WHEN: the workbook has no formulas (use xlsx_read). Or for upload/attached files.

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. 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.

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.

DO NOT USE WHEN: just reading values (use xlsx_read).

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. Operates on real cell values — formulas evaluated server-side, not the cached results that pandas trusts blindly.

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.

DO NOT USE WHEN: the user wants raw access to all rows (use xlsx_read). Or when the file came from an upload.

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. 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.

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.

DO NOT USE WHEN: just reading values (use xlsx_read).

extract every formula in a LOCAL .xlsx workbook — cell coord (A1), formula text, cached result. openpyxl-style read-only metadata. Distinct from xlsx_read which returns evaluated values; this returns the formulas themselves so an agent can audit, transform, or rewrite them.

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.

DO NOT USE WHEN: the user wants computed values (use xlsx_read). Or for upload/attached files.

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.

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.

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).

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.

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.

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).

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.

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.

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.

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.

USE WHEN: an agent or user wants to know "will this workbook work when I send it to ?" 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.

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).

list every hyperlink in a workbook with its anchor cell, target URL/anchor, display text, tooltip, and a kind classifier (external / internal / mailto / unknown). 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.

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.

DO NOT USE WHEN: trying to follow / fetch the targets (this tool does not fetch — by design, for safety). Or just reading cell text (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.

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.

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.

DO NOT USE WHEN: you want the image PIXELS (this surfaces metadata, not bytes). Or you only need cell values (use xlsx_read).

list sheet names, dimensions, and visibility for a LOCAL .xlsx file. Use this when you only need names + dims, not cell content. If you'll read content anyway, skip this and call xlsx_read directly.

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.

DO NOT USE WHEN: the file came from an upload/attachment (built-in skill handles that). Or when you already know the sheet structure. Or when you plan to call xlsx_read immediately after (just call xlsx_read).

Inspect xlsm / xlsb workbooks for VBA macro presence, vbaProject.bin size, and likely module names (ThisWorkbook / Sheet / Module / Class / UserForm via heuristic UTF-16LE scan). Returns short safety advice the LLM should relay to the user.

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.

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.

DO NOT USE WHEN: you need to actually inspect / debug VBA source — open the file in Excel (Alt+F11) on a trusted machine.

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. No other tool surfaces merges with master values rolled in: pandas drops merge metadata; openpyxl exposes ranges but not the master value alongside.

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.

DO NOT USE WHEN: you only need cell values and don't care about visual structure (use xlsx_read).

list all defined names (named ranges) in a LOCAL .xlsx workbook — name, scope (workbook or sheet), kind (cell / range / formula), reference. 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.

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.

DO NOT USE WHEN: the workbook has no formulas (named ranges are mostly relevant for formula contexts). Or for upload/attached files.

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. agg modes: sum / mean / min / max / count / count_distinct. Optional fill_value for missing index×column combinations.

USE WHEN: the user wants a cross-tab — "X by Y", "rows by columns" — that needs more than groupby. Returns a markdown table.

DO NOT USE WHEN: there's only one grouping dimension (use xlsx_aggregate). Or for upload/attached files.

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.).

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?".

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.

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).

upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message. 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). Posts via Slack's 3-step external upload flow (files.getUploadURLExternal → upload → files.completeUploadExternal), which is the only sanctioned path as of 2024+.

USE WHEN: the user asks "post this workbook to #channel," "share this with the team in Slack," or any other outbound-file-to-Slack request. The agent has just produced or modified a workbook and wants to deliver it. Free tier — counts against the 10k/mo cap.

DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that's the inbound Manual-Mode-Detector pattern, not this). Or when no Slack bot token is available — the user must have installed a Slack app with files:write scope.

Upload a local .xlsx file to a Microsoft Teams channel as a file attachment, with an optional accompanying message.

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.

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.

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.

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. 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.

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.

DO NOT USE WHEN: just reading values (use xlsx_read).

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.

Reads docProps/core.xml, docProps/app.xml, and docProps/custom.xml directly — a surface pandas drops entirely.

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.

DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to MODIFY metadata (use xlsx_redact for sensitive-field stripping).

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.

Reads sheetProtection action attrs directly from the OOXML zip (workaround for ExcelJS stripping them on round-trip).

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.

DO NOT USE WHEN: just reading values (use xlsx_read). Or trying to BREAK protection (this surfaces what's locked; it does not unlock).

xfa — read an .xlsx file by path and return a rendered markdown/JSON/SQL representation.

The path resolves on the SERVER's filesystem. In a LOCAL-CLI deployment (npx xlsx-for-ai-mcp) the server IS the user's machine, so /Users/..., /home/..., or ~-prefixed paths work directly. In a remote/hosted deployment the server runs on a different host — ingest user-provided files via the upload-handle flow first, then use xlsx_read_handle.

DEFAULT returns ALL sheets — do not re-call per-sheet. Pass sheet="" only to filter. format="md" (markdown table, default), "json", or "sql". Synonyms: "markdown"→"md", "text"→"md".

USE WHEN: the user gives a path the SERVER can reach (LOCAL CLI absolute or ~-prefixed; remote: a path on the hosted machine).

DO NOT USE WHEN: a paperclip/attach upload in a different agent (use that agent's built-in xlsx skill). Or user-provided files on a remote/hosted deployment (use xlsx_read_handle). Or in-memory bytes the agent already has.

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.

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.

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.

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.

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.

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.

DO NOT USE WHEN: the workbook was human-authored (use xlsx_stamp — Stamp attests to check results, Receipt attests to generation context).

redact PII and sensitive values from a LOCAL .xlsx file before sharing or archiving. DEFAULT preserves formulas + comments + named ranges + styles, strips only cell values. Pass strip_formulas=true / strip_comments=true to remove those too.

ALWAYS pass out_path when the user wants the redacted file saved to disk. WITHOUT out_path: redacted bytes return in _meta.file_b64 (base64) — caller must save them. The response text confirms whether a save happened — trust the response, do not infer.

USE WHEN: the user provides a LOCAL .xlsx path and wants PII removed. Server-side detection; returns a redacted copy with an audit manifest showing what was removed.

DO NOT USE WHEN: the file came from an upload/attachment. Or in sandboxed contexts without local filesystem access.

infer column schema of a LOCAL .xlsx file — types, nullable flags, header row, sample values. Use when the agent needs to reason about column types BEFORE deciding how to handle data. Includes confidence (high/medium/low) per column.

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.

DO NOT USE WHEN: the file came from an upload/attachment. Or for in-memory data the agent already holds.

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.

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.

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).

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.

Reads the OOXML zip (xl/slicers/, xl/slicerCaches/, xl/timelines/, xl/timelineCaches/) directly — a surface ExcelJS silently drops on round-trip.

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.

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).

pandas-style df.sort_values() on a LOCAL .xlsx file with multi-column sort and per-column direction (asc/desc, default asc). Stable across all sort keys; type-aware comparison; nulls always sort last.

USE WHEN: the user wants rows ordered by one or more columns. Returns the sorted rows as a markdown table.

DO NOT USE WHEN: the data is already sorted as desired (use xlsx_read). Or for upload/attached files.

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.

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.

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.

DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams).

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. 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.

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.

DO NOT USE WHEN: you only need the data (use xlsx_read which already includes basic numFmt hints in the output).

list every Excel ListObject ("Format as Table" structures) in a LOCAL .xlsx workbook — name, sheet, range, header/totals flags, columns. pandas cannot see ListObjects; if a workbook uses Excel Tables, this is the only way to enumerate them.

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.

DO NOT USE WHEN: the workbook has no Excel-Tables (just data ranges). Or for upload/attached files.

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). 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.

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.

DO NOT USE WHEN: you already know the sheet you want and just want its data (use xlsx_read or xlsx_describe).

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. 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.

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. Free tier — counts against the 10k/mo cap.

DO NOT USE WHEN: a casual read suffices (use xlsx_read). Or for upload/attached files.

pandas-style Series.value_counts() on one column of a LOCAL .xlsx file — count each unique value, sorted by frequency desc, with percentage. Excludes nulls by default; pass include_nulls=true to count them.

USE WHEN: the user asks "what's the distribution of X?" / "how often does each value appear?". Returns a markdown table.

DO NOT USE WHEN: the user wants groupby + multi-column aggregations (use xlsx_aggregate). Or for upload/attached files.

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). 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.

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.

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. 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.

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.

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.

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).

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.

DO NOT USE WHEN: just reading values (use xlsx_read).

create or update a LOCAL .xlsx file from a structured spec.

Spec shape: {sheets: [{name, cells: [{address, value | formula}]}]}. Each cell has an A1 address ("A1", "B2") and EITHER value (string|number|boolean|null) OR formula (string, no leading "="). Minimal example: {"sheets":[{"name":"Sheet1","cells":[{"address":"A1","value":"id"},{"address":"A2","value":1},{"address":"B2","formula":"A2*2"}]}]}

ALWAYS pass out_path to save to disk. Without out_path the workbook bytes return in _meta.file_b64.

USE WHEN: the user wants to write or edit a spreadsheet at a LOCAL file path. Server-validated before writing — safer than generating xlsx bytes directly.

DO NOT USE WHEN: working in a sandbox without local filesystem write access. Or editing an uploaded file in place (there is no local path to write to).