GridPath

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.

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.

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.

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.

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

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

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

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

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.

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.

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

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.

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

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.

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

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

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.

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

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

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, returned to you in the result as `script_logs` for debugging 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, 20,000 touche…

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.

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

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 }, ... ] }

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.

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.

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.

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

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

Remove any freeze panes from a sheet.

Unmerge a previously merged range.