All tools.

Get a structural map of the ACTIVE workbook without reading cell data. Per sheet: the used range, the detected header row with its period/column headers mapped to column letters (e.g. {"BU": "FY2026E"}), and a table of contents of sections — contiguous row bands with their titles, like {"rows": "5-42", "title": "Revenue build"}. Also lists workbook defined names. Served from an in-memory index, so it's near-instant and returns in ONE call what would take many read_range probes. Call it once to orient on any sheet whose preview is truncated. Optional sheet filters to a single sheet.

Search the ACTIVE workbook's row labels and column headers by name and get exact positions back — e.g. query "total revenue" returns each matching row's sheet, 1-indexed row number, containing section, and one evaluated sample cell ("BT209 = =BT194 → 39001.1") read live from the grid. Matching is case-insensitive substring plus word-prefix ("tot rev" matches "Total revenue"). Near-instant. Use this — NOT exploratory read_range probes — whenever you need to LOCATE a row or header ("where is Subscriber ARPU?", "which column is FY2027E?"); then read_range the exact range you need. Searches only the active workbook, not reference workbooks.

Filter, project and aggregate the rows of ONE sheet of the ACTIVE workbook by column values — served by the calculation engine in milliseconds on any sheet size. This is the tool for "which rows have AWS in the Owner column", "sites with capacity >= 100 MW online after 2026-01-01", or "total capacity by market": one call, instead of scanning with read_range or writing a script. Columns are column letters ("DB") or header texts from the sheet's header row ("Capacity (MW)", case-insensitive, unique substrings accepted); the header row is auto-detected (override with header_row). where lists predicates that are ANDed: op is one of eq, ne, contains, not_contains, starts_with, ends_with, gt, gte, lt, lte, between (value = [low, high]), in / not_in (value = list), empty, not_empty. Text compares case-insensitively and trimmed, numbers numerically, dates as ISO strings ("2026-01-01") against date-formatted cells. Returns the matching rows — 1-indexed row plus the requested columns keyed by column letter (date-formatted numbers come back as ISO dates) — up to limit (default 50, max 500), with matched = the total count and truncated. With group_by, returns one entry per distinct value with count and each requested aggregate (sum / count / min / max / avg) instead of rows. Read-only, evaluated values (set include_formulas for formulas too). Row numbers in the reply are exact — use them directly in formulas or read_range.

Read evaluated cell values from a specific A1 range WITHOUT modifying anything. Use this to verify your own work, confirm where the assumption block actually landed before composing dependent formulas, or pull current values you need to reference. Returns each non-empty cell's value AND formula (if any) in A1 = value form. Costs one tool turn but is the cheapest way to prevent the formula-pointing-at-wrong-row class of bug on long sheets. Range limited to 500 cells per call. To LOCATE a row/section/header by NAME, don't probe with this — use find_rows or describe_workbook first, then read the exact range.

Set the value or formula of a single cell. cell is an Excel A1-style address (case-insensitive, e.g. "A1", "B17", "AA42"). For formulas, pass them in formula starting with '=' (e.g. "=SUM(A1:A10)") — do NOT put formulas in value.

Set a rectangular block of values starting at top_left (A1 address). values is a 2D array — outer rows, inner cells. Strings starting with '=' inside values are treated as formulas; formula references must use A1 notation pointing at the FINAL placement of cells (e.g. if top_left is "A9" and the value at row index 2 / col 0 should reference the data row just above your block at A8, write "=A8" — not "=A1" or "=A11"). **Off-by-one guard: if formulas will reference rows created by THIS call, split the work — write labels + hardcoded values first, read the row_map in this call's result, then write formulas in a second set_range against those verified row numbers.** Composing formulas in the same call that lays out their target rows is the top source of off-by-one references. Use this for bulk writes; prefer it over many set_cell calls. **null and empty string "" inside values are treated as PRESERVE — the cell is left untouched, NOT cleared.** This means you can ship [["Gross Profit", "", "", ""]] to set only the label in column A without wiping the data in B–D. To actually clear cells, use clear_range. **Writing to a sheet name that doesn't exist CREATES that sheet automatically** (near-miss spellings of an existing sheet are rejected as probable typos) — so organize multi-section builds across purposefully named sheets (e.g. Data / Assumptions / Model / Notes) instead of piling everything onto one long sheet; a new tab costs nothing.

Copy a rectangular range to another location with Excel copy/paste semantics, executed against the LIVE grid: relative formula references shift by the paste offset exactly like Excel ($ anchors are respected — $B$5 stays put, B5 shifts), and cell formatting (number format, font, fill, alignment) travels with the cells. STRONGLY PREFER this over reading a range and re-typing shifted formulas yourself — it cannot make off-by-one mistakes and costs a fraction of the tokens. Ideal for: extending a projection by one more period (copy the last full year column block to the next column), duplicating a section as a template, or seeding a new sheet from an existing block. Blank source cells leave the destination untouched (they do NOT clear it). Result reports the evaluated destination values so you can verify. Limited to 5000 cells per call.

Empty the values AND formulas of cells in range. Use this when you want to delete content (not just overwrite with new values). range is an A1 range like "A1", "A1:F1", or "B2:D10". Cell formatting is preserved.

Execute a short JavaScript program against the workbook and land ALL its writes as one reviewable batch. STRONGLY PREFER this over long set_range payloads or many tool turns whenever the edit is loop-shaped: per-row conditional transforms ("for every row where margin < 0 …"), repeating formula patterns across many rows/columns, address arithmetic, or edits that depend on reading existing cells first. One run_script call replaces dozens of tool turns and cannot drift out of alignment mid-payload, because it computes addresses programmatically.

API (plain synchronous JavaScript, strict mode — no async/await, no imports, no network, no DOM):
sheets() -> array of sheet names
sheet(name) -> handle for one sheet (name must match exactly; the name arg may be omitted ONLY if the workbook has a single sheet). Handle methods:
.get("B7") -> {value, formula} — evaluated value as of BEFORE this script, overlaid with your own literal writes
.values("A2:C50") -> 2D array of values (rows × cols)
.set("B7", x) — write a value; strings starting with '=' are formulas; null clears the cell's content
.setValues("A9", [[...],[...]]) — bulk write with set_range semantics: null / "" preserve the existing cell
.format("A1:F1", {bold: true, number_format: "0.0%", background_color: "#1F4E79", font_color: "#FFFFFF"}) — same keys as set_format
.clear("B2:D10") — empty values + formulas, formatting preserved
.usedRange() -> "A1:Q48" or null
log(...) — up to 100 entries of up to 4,000 characters each (64 KB in total), returned to you in the result as script_logs. A cut entry ends with … [+N chars]. Logs are for debugging and small extracts; for bulk reads use query_rows / read_range, not a script that logs rows.

Rules: formulas you write are NOT evaluated during the script — .get on a cell you just wrote a formula into returns {value: null, formula}; the automatic readback after the script (cells + row_map) carries the evaluated results, so verify there. Follow the same conventions as set_range: write raw numbers (never pre-formatted strings), write formulas for derived values, compose against row_map. Limits: 5-second CPU cap, and at most 20,000 WRITTEN cells per script (set/setValues/format/clear combined). Reads are not budgeted: .values() over a whole region (even 7,000 rows × 100 columns) is the right way to scan, far cheaper than many read_range turns — do not narrow reads to save budget. Workbook size is not a limit either: the script is fed per sheet from the calc engine, so name every sheet you READ as a string literal (sheet("NA Data Center Supply")) — only named sheets are loaded; reading one you did not name errors; calling sheets() loads all of them. sheet("NewName") on a name that doesn't exist AUTO-CREATES that sheet when the script's writes land — use it to organize builds across purposeful tabs. Other structural ops (insert/delete rows or columns, sheet delete/rename, merges, freeze) are NOT in the script API — use the dedicated tools for those. The script's writes flow into the same pending batch as every other tool: the user reviews and can reject them.

Apply formatting to one OR MANY cell ranges in a single call. STRONGLY PREFER the bulk operations form when you have more than one format to apply — it's one tool call instead of N, dramatically faster. Each operation's format is a partial object; only specified properties are applied, others are left as-is. Use this for: bold headers, currency / percent / number formatting on data columns, italic notes, alignment, font color/size/family, **text wrap via wrap_text** (long methodology notes / descriptions in a fixed-width column — wrap beats restructuring the layout around overflow), and **cell fill via background_color** (e.g. dark-blue header bars, yellow assumption highlights — see the financial-model color conventions). v1 limitation: cell borders are not yet supported.

Two equivalent shapes:
• Single range: { sheet, range, format }
• Bulk: { sheet, operations: [ { range, format }, ... ] }

Set the pixel width of one or more columns. **Always prefer the bulk operations form when you need multiple widths** (e.g. label column A wide, data columns narrower) — one call instead of N. The flat single-width form is kept for trivial cases. Default Excel column is ~64px; a wide column for labels is typically 180–220.

Set the pixel height of one or more rows. **Always prefer the bulk operations form when you need multiple heights** (e.g. title row tall, body rows short) — one call instead of N. The flat single-height form is kept for trivial cases. Default row is ~24.

Merge a rectangular range into a single visible cell (e.g. for section headers). range is an A1 range like "A1:F1".

Unmerge a previously merged range.

Freeze the top rows rows and left cols columns of a sheet so they stay visible while scrolling. Classic financial-model setup is freeze_rows: 1, freeze_cols: 1 (lock the header row and label column). Pass 0 to disable that axis.

Remove any freeze panes from a sheet.

Hide one or more rows. rows is a comma-separated list of 1-indexed row numbers (e.g. "3" or "3,5,12"). Hidden rows still hold data but don't display in the workbook.

Unhide one or more rows. Same rows format as hide_rows.

Hide one or more columns. columns is a comma-separated list of column letters (e.g. "D" or "D,F,H").

Unhide one or more columns. Same columns format as hide_columns.

Attach a note (Excel-style cell comment) to a single cell — a small indicator that shows the given text on hover. Use this for methodology callouts, source citations, or caveats that would clutter the cell's own value. Overwrites any existing note on that cell.

Remove a cell's note, if it has one. No-op if the cell has no note.

Create (or replace) a workbook-scoped named range so formulas can reference a cell/range by a readable name instead of a raw address — e.g. name GrowthRate for the assumption cell, then write =Revenue*(1+GrowthRate). The name persists in the saved .xlsx. name must be a valid Excel name (letters, digits, underscores; can't look like a cell reference such as "A1"). ref must be sheet-qualified, e.g. "Model!B22" or "Model!B5:B12" (absolute $ signs optional — they're added automatically). Calling again with the same name replaces its target.

Insert count empty rows starting at (and shifting down from) row before (1-indexed Excel row number). Existing content at row before and below shifts down. Use this to make space in the middle of a model. Charts and conditional-formatting references in unrelated areas of the workbook may not auto-adjust to the new layout.

Delete count rows starting at row start (1-indexed). Content below shifts up. Permanent — the removed rows are gone.

Insert count empty columns starting at (and shifting right from) column before (column letter like "C"). Existing content shifts right.

Delete count columns starting at column start (column letter like "C"). Content to the right shifts left. Permanent.

Create a new sheet (worksheet tab) in the workbook. Use a clear human-readable name like "Assumptions", "Q4 2024", "Inputs". The new sheet starts empty — write cells with set_cell / set_range afterwards. NOTE: writes to a not-yet-existing sheet name auto-create it, so an explicit create_sheet is only needed when you want to set a tab_color or create an empty tab ahead of time.

Rename a sheet. Cross-sheet formula references in other sheets will be updated automatically by the workbook engine.

Remove a sheet from the workbook. Permanent — every cell on this sheet is lost. Cross-sheet references in other sheets will become #REF!.

List this workbook's pending (unsaved) change batches with their mutation counts, and the review link.

Drop one pending batch. The remaining batches are replayed onto a fresh model, so later edits that depended on it may change.

Write every pending batch into the .xlsx on disk through the surgical patcher: only the parts an edit touched are rewritten, everything else stays byte-identical. This is the ONLY tool that modifies the file. When the server runs with --review-required, this returns the review link instead and the user saves from there.