GRID Agent Tools

Load an .xlsx file into memory and make it the active workbook. A session starts with this or createWorkbook. Returns the sheet names.

Create a blank single-sheet workbook in memory and make it the active workbook. Nothing is written to disk until saveWorkbook.

Save the active workbook to an .xlsx file. Provide a new path, or set overwrite: true to write over an existing file (including the source).

List all loaded workbooks and their sheet names.

Takes no parameters.

Make a previously loaded workbook the active one for all other spreadsheet tools. Switching keeps in-memory state, so unsaved edits survive. Use listWorkbooks to see what is loaded; use loadWorkbook to (re)load from disk.

Analyzes the spreadsheet and returns a structured description of all data regions, headers, and labels. This helps you understand: - Where data tables are located (islands/regions) - Which rows are headers vs data - Column and row labels for each data region - Sheet names and their contents - Whether iterative calculation is on (needed for intentional circular references) Labels are limited to 50 per sheet. Use totalLabels to check if more exist, and labelOffset to paginate. Use this information to write accurate formulas that reference the correct cells and ranges.

Read cell values, formula results, and lookups from spreadsheets, and optionally apply temporary values for what-if calculations. The 'read' array accepts cell references, ranges, and formulas. Use formulas like XLOOKUP, QUERY, AVERAGE, etc. directly in 'read' to find and compute values in a single call. Examples: - Read cells: { "read": ["A1", "B1:B10", "Sheet2!C5"] } - Lookup: { "read": ["=XLOOKUP(\"Revenue\", A1:A10, B1:B10)"] } - Filtered average: { "read": ["=QUERY(Sheet1!A1:D100, \"SELECT AVG(D) WHERE A = 'Category1'\")"] } - What-if: { "read": ["C8"], "apply": [{ "cell": "B1", "value": 100 }] } Large ranges are automatically truncated. When a range entry is truncated the response includes `nextOffset` — call again with `cursors: { "<same expression>": <nextOffset> }` to read the next page.

Permanently write values or formulas to cells. Merge or unmerge cells. IMPORTANT: After editing, you MUST call readCalculatedValues to see the resulting changes. The tool returns a delta showing changes, but you should verify formulas propagated correctly. Writing text over a cell that held a number or date is reported in `warnings` (level "high" or "low"). A "high" warning usually means a real value was turned into a text string that only looks the same — write the value itself, not its displayed text. Examples: - Set value: { "apply": [{ "target": "A1", "value": 100 }], "note": "Set initial value" } - Set formula: { "apply": [{ "target": "B1", "value": "=A1*2" }], "note": "Add formula" } - With style: { "apply": [{ "target": "A1", "value": 100, "styleIndex": 0 }], "styles": [{ "bold": true }], "note": "Bold value" } - Merge cells: { "apply": [], "merge": ["A1:B2"], "note": "Merge header" } - Unmerge: { "apply": [], "unmerge": ["A1:B2"], "note": "Unmerge cells" } Formulas must start with "=". Values are auto-detected as number, boolean, or string.

Extend a selection by filling cells with auto-detected patterns (numbers, dates, formulas). Similar to Excel's fill handle - detects sequences and continues them. Fill direction is inferred from selection and extend_to: the dimension that changes determines the fill axis. IMPORTANT: After filling, you MUST call editCellStyles to apply formatting to the filled cells. Examples: - Fill down: { "sheet": "Sheet1", "selection": "A1:A3", "extend_to": "A1:A10", "note": "Extend series" } - Fill right: { "sheet": "Sheet1", "selection": "A1:C1", "extend_to": "A1:F1", "note": "Extend headers" } - Fill up: { "sheet": "Sheet1", "selection": "A8:B10", "extend_to": "A1:B10", "note": "Extend upward" }

Apply formatting styles to cells without changing values. IMPORTANT: After using fillCells, you MUST call this to apply formatting to the filled range.

Add, remove, rename, or change visibility of sheets. Operations are executed in order: add → rename → setVisibility → remove.

Insert, delete, or auto-size rows and columns. Operations are executed in order: column insert → column delete → row insert → row delete → column autosize → row autosize.

Run one or more formulas without writing to any cell. Returns the calculated results. Useful for testing formulas or computing values without modifying the workbook. Examples: - Single: { "formula": "=SUM(A1:A10)" } - Batch: { "formulas": ["=SUM(A1:A10)", "=AVERAGE(B1:B10)", "=COUNT(C1:C10)"] } - With temp values: { "formula": "=A1*B1", "apply": [{ "cell": "A1", "value": 5 }] } - Against a specific sheet: { "formula": "=SUM(A:A)", "sheet": "Sheet2" } Use "formulas" array to test multiple formulas in one call (more efficient than multiple calls). Bare cell references (e.g. A1, SUM(A:A)) resolve against the primary workbook's first sheet by default. Use the "sheet" parameter when you need them to resolve against a different sheet. The response includes a "_note" field identifying the sheet bare references resolved against, so you can verify they resolved where you intended. Sheets in external (linked) workbooks can be read with workbook-qualified references inside the formula itself, e.g. ='[external.xlsx]Sheet1'!A1. If an external sheet shares its name with a sheet in the primary workbook, the primary workbook's sheet always wins for plain references — only the workbook-qualified form reaches the external one.

Find the input value needed to achieve a target result (like Excel's Goal Seek). Iteratively adjusts the control cell until the target cell reaches the desired value.

Test hypothetical value changes and see which formula cells are affected. Applies temporary changes, recalculates, shows before/after diff of affected formula cells, then restores the original state. A string value starting with "=" is applied as a temporary formula. Max 20 changes, max 100 affected cells reported. Example: { "changes": { "A1": 50, "B1": "=A1*2" } }

Get the workbook's style definitions. Returns styles where each index corresponds to a style_index in cell data. Use this to understand what formatting (colors, fonts, borders, etc.) is applied to cells. If no indices are provided, returns all styles as an array. If indices are provided, returns only those styles as an object keyed by index.

Read the full text of the comment or note on a specific cell, including all replies for threaded comments. Returns kind="none" if the cell has neither. Use after `getComments` to see the body of an entry whose preview was truncated, or when an agent message refers to a specific cell with a TODO/question on it.

List the cells in the workbook that have a comment or note attached, with author, kind (threaded comment vs. legacy note), reply count, and a short text preview. Comments are how a reviewer flags TODOs, justifies a number, or asks a question on a specific cell — read them when auditing, debugging, or completing a partly-built workbook. Returns up to 25 entries; pass `offset` to page. Use `getComment` to read the full text or thread for a specific cell.

Trace downstream dependents — the cells that read from a given cell, transitively. Default mode 'grouped': cells sharing a formula pattern are collapsed into labeled chunks, labeled from nearby headers. This provides a token-efficient structural view that shows how values flow from parameters through intermediate calculations to outputs. Switch to mode: "cells" to drill into individual cells: each node carries the formula, value, and error of the dependent cell so you can see exactly how a value propagates through the sheet. When a formula uses a range, Apiary resolves range containment internally; the dependent formula appears as a direct child of the queried cell rather than via an intermediate range node. "grouped" response shape — each node carries: - type: "output" (computed, no dependents), "inter" (computed, has dependents), "data" (value range), "param" (single value cell) - labels: human-readable names derived from nearby headers - formula: the formula pattern for this chunk (with relative references) - rootHeight: dependency distance from graph roots (parameters/data) - leafDepth: dependency distance from graph leaves (outputs) - dependents: dict of downstream chunk nodes keyed by their ref (omitted for terminal outputs) - alreadyVisited: true when this chunk was expanded elsewhere in the tree (diamond/cycle cut) - truncated: present when traversal stopped early; reason is "maxDepth" or "maxNodes"; totalChildren reports the real count when children were cut short "cells" response shape — each node carries: - kind: "cell" or "name" - formula: the formula string, or null for value cells - value: the calculated value - errorValue: present only when the cell evaluates to a formula error - dependents: a dict of child nodes keyed by their own ref (omitted for leaves with no downstream consumers) - alreadyVisited: true when this node has been fully expanded elsewhere in the tree (diamond/cycle cut) - truncated: present when traversal stopped early; reason is "

Trace upstream dependencies — the cells a formula reads from, transitively. Default mode 'grouped': cells sharing a formula pattern are collapsed into labeled chunks, labeled from nearby headers. This provides a token-efficient structural view that surfaces which parameters feed into which outputs. Switch to mode: "cells" to drill into individual cells: each node carries the formula, calculated value, and error (e.g. #DIV/0!) so you can follow error propagation to its source. Ranges referenced by formulas appear as 'range' nodes. If every range member is a leaf value cell, the range is collapsed into a single node with no further children. "grouped" response shape — each node carries: - type: "output" (computed, no dependents), "inter" (computed, has dependents), "data" (value range), "param" (single value cell) - labels: human-readable names derived from nearby headers - formula: the formula pattern for this chunk (with relative references) - rootHeight: dependency distance from graph roots (parameters/data) - leafDepth: dependency distance from graph leaves (outputs) - precedents: dict of upstream chunk nodes keyed by their ref (omitted for leaves) - alreadyVisited: true when this chunk was expanded elsewhere in the tree (diamond/cycle cut) - truncated: present when traversal stopped early; reason is "maxDepth" or "maxNodes"; totalChildren reports the real count when children were cut short "cells" response shape — each node carries: - kind: "cell", "range", or "name" - formula: the formula string, or null for value cells and range vertices - value: the calculated value (cell and name nodes) - errorValue: present only when the cell evaluates to a formula error - precedents: a dict of child nodes keyed by their own ref (omitted for leaves) - alreadyVisited: true when this node has been fully expanded elsewhere in the tree (diamond/cycle cut) - truncated: present when traversal stopped early; reason is "maxDepth" or "maxNodes"; totalChildren reports the real coun

Inspect detailed per-cell information including value, formula, number format, style, and hyperlink. Returns up to 20 cells per call. When the range is larger, the response is truncated and includes `nextOffset` — call again with the same `reference` and `offset: <nextOffset>` to continue. Examples: - Single cell: { "reference": "A1" } - Range: { "reference": "B2:C5" } - Cross-sheet: { "reference": "Sheet2!A1" } - Next page: { "reference": "A1:K10", "offset": 20 }

List all formula errors and model errors in a workbook, grouped by error, detail and origin (the cell where the error arose). Errors saved in the file are recalculated to find their origin and detail. Results are scoped to a sheet or range when provided, and truncated per group when the default cell limit is exceeded.

Get workbook structural metadata: sheet dimensions, named ranges, tables, and dependency graph stats. Complements describeStructure (which provides labels and data regions) with structural/entity information. Use this to understand the workbook's overall shape before inspecting specific cells.

Takes no parameters.

Render a worksheet rectangle as a compact text grid — by default the displayed (number-formatted) values, what a human sees in the cells — with column letters and row numbers. Use this FIRST to scan or orient in an area (a financial statement, a block, a table): one call returns the whole rectangle instead of reading it cell-by-cell. Pass `show` to audit other layers of the same grid: raw unformatted values, a style property ('-' marks unset cells), or the formula structure — formula cells get a legend key, identical fills share one key, so a miscolored cell, a wrong format, or a hardcoded override stands out against the value grid you just read. For precedents/dependents or error provenance, use `inspect`. Returns at most 500 cells; a larger rectangle marks the cut with *** TRUNCATED *** and ends with a note naming the rows or columns that remain — request those in a follow-up call. Examples: - Range: { "reference": "B40:N80" } - Sheet-qualified: { "reference": "'LBO Model'!B40:N80" } - Single cell: { "reference": "C12" } - Font colors: { "reference": "B40:N80", "show": "fontColor" } - Formula structure: { "reference": "B40:N80", "show": "formula" }

Search for cells matching specified criteria within a sheet or range. Returns up to 200 matches. Use matchMode to control whether all criteria must match (AND, default) or any (OR). Range iteration is limited to 10,000 cells — use sheet scope for larger searches.

Render a range as a PNG image and return its raw bytes (Uint8Array). Use this when the formatting itself is the information — fills, font colors, borders, merged cells, number formats — that the text-grid tools (viewRange) can't convey, or when the user asks to *see* part of the workbook. The bytes are ready to attach to a multimodal message or write to a file; this tool does no LLM wiring itself. Gridlines and row/column headers render as Excel shows them. Renders against the browser's native canvas when available, and skia-canvas in Node.

Generate a comprehensive natural-language description of the active workbook: sheet structures, data regions, labels, and relationships. More detailed than describeStructure.

Takes no parameters.

Execute an Office.js code snippet directly against the active workbook. Returns any error plus the list of Office.js APIs the code used that are not yet implemented. Edits synced before a script error remain applied.