Report the KitchenSink4XL server build: version, the active tool surface (enabled tool count and approximate token bill), the available optional packs, and the host platform and Python. A read-only orient call that needs no workbook and touches no file; use it to confirm the server is reachable and to see which packs are currently loaded before deciding whether to call enable_tools.

Create a new .xlsx workbook at path with the given sheet names (default a single 'Sheet1'). Sheet names must be unique, at most 31 characters, and may not start or end with an apostrophe (Excel refuses to open such a file); the parent directory must already exist. An existing file at path is left untouched unless overwrite is true, in which case it is FIRST rotated into its .ks4xl-backups prev slot and then replaced (restore source='prev' brings it back). Returns the file path and the sheets created.

Copy a workbook file byte-for-byte from src to dst, so nothing in the original is re-serialized or degraded (charts, shapes, macros, and queries all carry over intact). An existing dst is left untouched unless overwrite is true, in which case dst is FIRST rotated into its .ks4xl-backups prev slot and then replaced (restore source='prev' brings it back). Returns the destination path. Use this to branch a working copy before a risky batch of edits.

Read a workbook's structure without opening it for edit: every sheet with its visibility state, TRUE used range (value-bearing bounds, not the often wrong stored dimension), dimensions, and merged-cell count, plus defined names, tables, the active sheet, and a round-trip hazard summary (whether an openpyxl edit would drop fragile parts). The orient-before-editing call. Read-only; works while the file is open in Excel.

The round-trip hazard scan surfaced as a health readout: which fragile parts the workbook holds (slicers, shapes, embedded objects, Power Query, VBA, and the rest), whether a file-based openpyxl edit would drop any of them, the routing recommendation for a surgical versus a structural edit, and a light integrity summary (sheet counts, formula-cell count, keep_vba). This is how you check a workbook is safe to edit before mutating it.

What to do with the verdict: hazards never block reads; a would-lose verdict means every mutating tool will refuse unless you route through Excel (com pack) or pass allow_loss:true (an explicit, backed-up acceptance of the loss). A clean verdict means file-based edits are round-trip safe. Content with no part of its own is covered too: the scan reads each worksheet's extLst, so x14 conditional formats (data bars, icon sets), sparkline groups and slicer lists come back as a would-lose verdict like any other drop-risk hazard. Limit: the extLst walk looks at the worksheet's top level, and an extension openpyxl drops from anywhere else is caught at save time by openpyxl's own load warning rather than here. Read-only.

Manage the worksheet lifecycle. action is one of: add (new_name, optional index), delete (sheet), rename (sheet, new_name), copy (sheet, optional new_name), reorder (sheet, index as 0-based target), hide (sheet, state 'hidden' or 'very_hidden'), unhide (sheet). The workbook always keeps at least one VISIBLE sheet, so deleting or hiding the last visible one refuses.

Consequence worth knowing: delete does NOT rewrite references, so formulas and defined names that pointed at the deleted sheet break to #REF! when Excel opens the file (Excel's own behavior); rename likewise does not rewrite cross-sheet formula text. Audit references first when in doubt. A hazardous workbook refuses unless allow_loss is true. Auto-backup: prev/anchor slots in .ks4xl-backups (backup=false skips rotation); atomic verified save, restored on failed verify. Refuses while open in Excel.

Read a cell or range addressed by a location object (cell, range, r1c1, name, table, used_range, region, search, or a grid-view anchor; sheet picks the sheet when the location does not, default active). values controls the honest calc story: 'cached' returns the last calculated values, 'formula' the formula strings, 'both' pairs each value with a label (cached, absent, formula, value). A formula cell with no cached value is labelled 'absent', never passed off as blank. Read-only; page large ranges with query_range.

Write a single cell addressed by a location object. A string beginning with '=' is ALWAYS stored as a formula (there is no literal escape), normalized so modern functions do not land as #NAME? and flagged to recalculate on open; anything else is a literal. A hazardous workbook refuses unless allow_loss is true. Auto-backup: prev/anchor slots in .ks4xl-backups (backup=false skips rotation); atomic verified save, restored on failed verify. Refuses while open in Excel.

Write a 2D block of values and formulas anchored at the location's top-left cell. data is a list of row lists and must be RECTANGULAR: ragged rows refuse (pad short rows with null, which clears those cells); content outside the block is never touched. Formula strings ('=...') are normalized and flag recalculation. Grid limits and the 200,000-cell write ceiling apply. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Clear a cell or range: what='contents' removes values and formulas, 'formats' resets styles to default, 'all' does both. Neither removes merges, conditional formats, validations, comments, or hyperlinks; those have their own manage tools. Addressed by a location object. A hazardous workbook refuses unless allow_loss is true. Auto-backup: prev/anchor slots in .ks4xl-backups (backup=false skips rotation); atomic verified save, restored on failed verify. Refuses while open in Excel.

Copy a source rectangle to a destination anchor (location objects, may name different sheets). what is 'all', 'values', 'formulas', or 'formats'. The destination is overwritten; the source is buffered first, so an overlapping paste is safe. Relative refs in copied formulas shift by the paste offset like an Excel copy unless adjust_formulas is false; absolute ($) anchors stay put. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Move a rectangle to a new anchor on the same sheet, rewriting every formula, name, conditional format, validation, table ref, and merge that pointed into the source so references follow the cells (Excel move semantics). A cross-sheet destination refuses (copy_range then clear_range instead); cells at the destination are overwritten. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Filter, project, sort, paginate, and aggregate a range SERVER-SIDE so an agent reads only the rows and columns it needs instead of a whole sheet.

location defaults to the sheet's true used range. With header=true the first row names the columns (referenced by name; otherwise by A1 letter). where is a list of {column, op, value} predicates joined by match ('all' or 'any'); ops: eq, ne, gt, ge, lt, le, contains, startswith, endswith, regex, in, not_in, is_blank, not_blank. columns projects a subset; order_by is a list of {column, dir} specs (unknown directions refuse); offset and limit page; distinct dedupes. aggregate is a list of {column, func} (count, count_nonblank, count_distinct, sum, avg, min, max, first, last), optionally per group_by, returning group summaries (records=true emits objects).

Semantics: predicates read CACHED and literal values (uncalculated formulas read as blank; recalc for exact results); gt/ge/lt/le compare numerically when both sides coerce, else case-folded text; blanks never satisfy ordered comparisons; regex is timeout-guarded. Aggregates follow Excel: sum/avg/min/max consume NUMERIC cells only (text and booleans ignored even when text looks numeric; exclusions are reported); count is the RAW row count, unlike Excel COUNT; min/max fall back to text when no numbers exist. Read-only.

A compact, token-efficient projection of a sheet or range: the true used range, a markdown table with A1 addressing (column letters across the top, row numbers down the side), formula and merged-cell markers, dimensions, and the hazard summary, so an agent can see the grid without a per-cell JSON dump.

location defaults to the sheet's used range. values='cached' shows last calculated values with formula cells marked (the florin character U+0192 marks a formula with no cached value); 'formula' shows the formula strings. The view paginates with max_rows and max_cols (caps 200 and 100) and reports truncated flags so the caller knows when to page. formula_cells maps addresses to their formula strings; merged ranges intersecting the view are listed. The result's anchor is a token for the shown rectangle: {"anchor": token} addresses it in any positional tool, refusing STALE_ANCHOR if the region changed since this view; cells inside stay plain A1. Read-only; works while the file is open in Excel. Pair it with apply_edits to edit what you see.

Apply many addressed edits as ONE atomic batch. edits is a list of {op, location, ...}: set_value {value}, set_formula {formula}, clear {what: contents|formats|all}, write_range {data: 2D array}. location is any location object, including a stale-checked get_grid_view anchor.

Every location is resolved and every op validated BEFORE anything is written, so a single bad edit refuses the whole batch and the file stays byte-for-byte unchanged. The batch then takes ONE backup (prev/anchor slots in .ks4xl-backups), does ONE atomic save, and runs ONE verify-after-write, which restores from the backup if the produced file fails to read back as intended. Formula edits are normalized and flag recalculation; each write_range op honors the 200,000-cell ceiling. A hazardous workbook refuses unless allow_loss is true; refuses while the file is open in Excel. Returns the count of edits applied and cells touched.

Apply formatting to a range, merging onto the existing style so unspecified attributes are preserved. number_format is an Excel format code; font is {name, size, bold, italic, underline, strike, color}; fill is {color} or {pattern, fg, bg}; border is {style, color, sides}; alignment is {horizontal, vertical, wrap_text, text_rotation, indent}; colors are hex. Named styles and conditional formats: design pack. Hazard-gated (allow_loss overrides); auto-backup; atomic verified save. Refuses while open in Excel.

Set column widths and row heights, hide rows or columns, and service an autofit request. column_widths maps column letters or indices to widths in Excel character units; row_heights maps row numbers to heights in points; autofit_columns sizes columns to content as a best-effort APPROXIMATION (true autofit needs Excel via the com pack). A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Turn a range into an Excel table (ListObject) named name. With header true the first row supplies the column names (deduplicated); style is a built-in style; row_stripes and col_stripes toggle banding. totals maps columns to a function (sum, average, count, min, max...). Refuses an overlap with an existing table, and a name already taken by a table or defined name. Hazardous workbooks refuse unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Read a table's data by its name (case-insensitive). columns projects a subset; values is cached | formula | both (the honest calc story); records true returns row objects keyed by column name. Returns the table ref, the column names, and the data rows without the header or totals row; filter or page big tables with query_range and a {table} location. Advanced table ops (columns, totals, resize, banding): manage_table (design pack). Read-only; nothing is written.

Sort a range or table body by one or more keys, writing the rows back reordered. keys is a list of {column, order}: header name, letter, or 1-based index; asc or desc; later keys break ties. has_header keeps the first row put. Moved formulas shift relative refs (Excel semantics); keys compare cached values, warning when uncalculated. Filter-hidden rows stay pinned and unsorted, as in Excel. Hazardous workbooks need allow_loss. Auto-backup (prev is the undo); atomic verified save. Refuses while open in Excel.

Apply an autofilter over a range whose first row is the header, and actually hide the non-matching rows: an .xlsx stores filter CRITERIA, not hidden state, so criteria (a list of {column, op, value}, ops as in query_range, combined as AND) are evaluated here over cached and literal values; a row whose tested cell holds an uncalculated formula stays visible with a warning. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Remove the autofilter from a sheet and unhide the rows it hid, the reverse of set_filter. location or sheet picks the sheet; the sheet's active autofilter range is used when location is omitted. A sheet with no autofilter refuses (NOT_FOUND) rather than silently no-opping. Returns how many rows were unhidden. A hazardous workbook refuses unless allow_loss is true. Auto-backup: prev/anchor slots in .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Manage cell hyperlinks. action is add (location, target as a URL or an in-workbook 'Sheet!A1' reference, optional display text and tooltip), remove (location), or list (read-only). On add, display replaces the cell's value; with no display an empty cell shows the target. remove strips only the link: the cell's text and style stay. On list it surfaces both real cell hyperlinks and HYPERLINK() formula links so an audit sees every kind. For the mutating actions: a hazardous workbook refuses unless allow_loss is true; auto-backup to prev/anchor slots in .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Import CSV, TSV, or JSON into a sheet at an anchor. Pass source (inline text) or source_file (a path); fmt auto-detects from the extension. location is the top-left anchor (default A1). A cell whose text begins with =, +, -, or @ is written as TEXT to block formula injection unless formulas is true. An import past the 200,000-cell write ceiling refuses rather than dropping rows. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Export a range, table, or sheet to CSV, TSV, or JSON. location defaults to the sheet's true used range; {table} exports a table. values is cached | formula | both; the result states the mode used. out_file writes to a file; otherwise text returns inline. The target is guarded: never the source workbook, a workbook extension, or .ks4xl-backups; an existing file refuses unless overwrite is true, which first keeps a timestamped .bak. Multi-sheet export is export_file (io pack). Read-only; the workbook never changes.

Insert or delete rows or columns at a position and REWRITE EVERY REFERENCE so the workbook stays coherent: formulas on every sheet (cross-sheet refs included), defined names, data validations, conditional-format ranges, table refs, and merged ranges all shift with the edit. action is insert_rows, delete_rows, insert_cols, or delete_cols; at is the 1-based row number or column letter where the edit starts (a cell like 'B7' or a location object also works, using its top-left); count edits that many at once.

Whole-column spans like =SUM(B:B) and whole-row spans like $1:$2 shift on their own axis; an edit on the other axis leaves them alone (Excel's behavior). A reference wholly inside a deleted band becomes #REF! and the new-#REF! count is reported, never hidden; an insert that would push value-bearing cells off the grid edge refuses. Returns per-kind rewrite counts. A hazardous workbook refuses unless allow_loss is true. Auto-backup: prev/anchor slots in .ks4xl-backups (backup=false skips rotation); atomic verified save, restored on failed verify; the prev slot is the undo for a delete. Refuses while open in Excel.

Merge or unmerge cell ranges, or list every merge. action is merge (location is the multi-cell range), unmerge (location must be the exact stored merged range), or list (read-only, one sheet or the whole workbook). Excel merge semantics: only the top-left value survives, so a merge whose absorbed cells hold values REFUSES until you pass confirm_data_loss=true, then reports exactly which values were discarded; overlapping an existing merge refuses. Unmerge keeps the surviving top-left value and leaves the rest blank. For the mutating actions: a hazardous workbook refuses unless allow_loss is true; auto-backup to prev/anchor slots in .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Search cell values and/or formulas across a workbook, sheet, or range and return EVERY match with its unambiguous address (the plural sibling of the single-target search location selector). match is exact, contains, or regex (timeout-guarded, so a pathological pattern refuses instead of hanging); look_in is values, formulas, or both; a formula cell's searchable value is its last cached one. Results page with limit and offset and report the total match count. Read-only; works while the file is open in Excel.

Find-and-replace across a workbook, sheet, or range. match is exact (whole cell), contains (literal substring), or regex (timeout-guarded; backreferences like \1 work in replace). look_in 'values' rewrites literal cells, 'formulas' rewrites formula text (the cell stays a formula, normalized), 'both' does both. dry_run=true previews every change without touching the file; a real run validates the whole plan first, applies it as ONE batch, and reports cells changed and occurrences replaced. A replaced value that parses as a number is written as a number; replacement text beginning with =, +, -, or @ is written as TEXT to block formula injection unless formulas is true. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Read many individually addressed cells in one call, the scatter complement to the rectangular read_range. cells is a list of A1 strings or location objects, each resolving to ONE cell (1,000-cell ceiling); values is cached, formula, or both, and every returned value carries the honest label (cached, absent, formula, value), so a formula with no cached value is never passed off as blank. Read-only; works while the file is open in Excel.

Write many individually addressed cells as ONE atomic batch, the scatter complement to write_range. cells is a list of {cell, value} items (cell is an A1 string or a location object resolving to one cell; 1,000-cell ceiling); every address is resolved BEFORE anything is written, so one bad item refuses the whole batch untouched. '=' strings become formulas, normalized. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Write a formula to a single cell, or fill a range where each cell gets the formula with its relative references shifted by that cell's offset (Excel copy semantics; absolute $ anchors stay put). Formulas are normalized so modern functions do not land as #NAME?, and the workbook is flagged to recalculate on its next open; stored cached results stay stale until then (the recalculate tool in the com pack populates them). Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Read-only formula intelligence for a range, one sheet (sheet alone), or the whole workbook (no scope): the formula list plus five safety reports. external_references flags formulas reaching into other workbooks; volatile lists always-recalculating functions (NOW, RAND, OFFSET, INDIRECT and kin); missing_cached_values names formula cells with NO stored result, which read as blank to every non-Excel consumer until a recalculation; error_cells catches #REF!, #NAME?, and the other error literals in cached results or formula text; and cross_sheet_dependencies summarizes which sheets' formulas depend on which. Each list is capped with exact counts and a truncated flag. Use it before and after structural edits, and to judge whether cached values can be trusted. Read-only; works while the file is open in Excel.

Run read-only correctness checks and return one report. checks (default ['structure', 'references', 'calc_staleness']): structure (package opens clean, sheet integrity), references (#REF!/#NAME? and the other error cells), names (broken defined names), merges (overlapping or orphaned merged ranges), tables (duplicate names, broken refs, overlaps), formatting_bloat (the audit_styles counters against the 64,000-format ceiling), hazards (the round-trip scan as a check), external_links (links reported, not repaired), calc_staleness (formulas lacking cached values, which read as blank outside Excel). Returns {passed, results: {check: {passed, findings}}}; findings keep the underlying ops' shapes where those exist, and passed=false means findings, not a failed call. Read-only, always; repairs live in the editing tools. Works while the file is open in Excel.

Recommended tool sequences for common multi-step spreadsheet tasks, each step naming the tool, the rationale, and the pack it lives in (lite is always on; enable_tools loads the rest). Call with no task to list the available tasks (merge-workbooks, report-build, data-cleanup, formatting-audit-and-fix, safe-edit-of-rich-workbook, migrate-from-incumbent); call with task='' for that task's step-by-step recipe and notes. Steps naming COM-tier tools that have not shipped yet are marked forthcoming rather than pretended present. Pure guidance: reads nothing, changes nothing.

Manage the automatic backups in the hidden .ks4xl-backups folder next to each mutated workbook: two rotating slots per file, prev (state before the most recent mutation) and anchor (session start). action='list': slot files with sizes and mtimes plus orphaned slot folders; give path for one workbook or directory for a folder. action='restore': overwrite path with source 'prev' or 'anchor'; the current content rotates into prev FIRST so a restore is itself undoable, the payload is validated as a real workbook before the atomic replace, and files open in Excel refuse. action='purge': delete backups; scope is 'orphans' (slot folders whose workbook is gone) or 'slots' (one workbook's pair); dry_run defaults to TRUE and only reports. action='snapshot': save a permanent DTG-stamped copy, YYYYMMDD_HHMM_, optional label and dest_dir; snapshots are never rotated and no purge scope touches them. LIMIT, stated loudly: prev holds the state before the LAST mutation this server made, so damage that lands AFTER the last save (crash, disk, another program) costs that final edit; only a snapshot habit covers it. Lost or corrupt file? get_workflows task='recover-workbook' is the walkthrough.

Set core document properties (title, author, subject, keywords, category, comments) and calc settings: calc_mode ('auto', 'autoNoTable', 'manual'), full_calc_on_load, and iterative calculation (iterative_calc with max_iterations and max_change bounds for circular references). Only given parameters change; with none it reports current values read-only. Manual mode means no recalc on Excel open, so caches go stale; the result says so. Auto-backup; atomic verified save. Refuses while open in Excel.

Set sheet-view state in one call: freeze panes (freeze='B2' locks the rows above and columns left of it; 'clear' removes), split panes (split={x, y} positions in points, exclusive with freeze), gridlines and headings visibility, zoom (10 to 400 percent), the active selection (an A1 cell or range), and the sheet tab color (6-digit hex or 'clear'). Unset parameters keep their current values; sheet defaults to the active sheet. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Enable optional tool packs mid-session (sessions start lite). Idempotent; reports tokens added. packs = names below or ['everything']; disable_tools reverses it. Refuses under KS4XL_PACK_POLICY=locked. Task map: conditional formatting, data validation, named styles, images, charts, advanced table ops, named ranges -> design; page layout, headers/footers, protection, comments, whole-file export, external links, VBA, pivot and connection info -> io; recalculate, real pivots, PDF, render, convert, encrypt, autofit, sparklines, goal seek -> com. Packs:

• design (~3.4k): workbook design and rich features: named cell styles, format painter, style-bloat audit, conditional formatting, data validation, images, charts (create/list/delete), advanced table lifecycle (columns, totals, resize, banding), and named ranges (define, scope, LAMBDA, cleanup)

• io (~2.5k): page layout and print, headers/footers, advisory protection, legacy comments, multi-sheet export, and the read-side inspectors: external links, VBA, existing pivots, data connections

• com (~2.6k): drives a private hidden Excel instance (Windows + Excel required): real pivot tables, fidelity recalculation, goal seek, PDF export, sheet render to image, format conversion, real encryption, sparklines, true autofit, opens-clean validation, and honest status; never touches your open Excel session

Disable previously enabled tool packs for this session and reclaim their context; the lite core always stays on. Idempotent. The result reports the packs just disabled, the approximate tokens removed, and the remaining surface. packs takes the same names as enable_tools (its description carries the menu) or ['everything']. Calling a tool from a disabled pack does not dead-end: the refusal names the owning pack and the exact enable_tools call to turn it back on. Refuses when the host pins the surface with KS4XL_PACK_POLICY=locked.