Start the workbook you will work in. Call with no arguments for a fresh, empty one; pass path to load an existing .xlsx from disk and work on the human's real file.

This replaces whatever workbook the session currently holds, discarding unsaved changes — so call it once at the start, not between steps. You do NOT have to call it at all: an empty workbook appears automatically the moment any other tool touches the session.

Prefer path over xlsx_base64. xlsx_base64 exists for hosts with no shared filesystem and costs enormous context for a file of any size.

Write the workbook to a real .xlsx file the human can open in Excel. This is how you hand your work back — do it when the task is done.

Defaults to the path it was opened from, or last saved to; pass path to write somewhere else. Values, formulas and the block structure are all saved.

IMPORTANT — if the human is going to work on this in Excel, pass resolve_block_refs: true. Formulas that read blocks are written as BLOCKREF/BLOCKREFS, which only LogiSheets understands: Excel shows the saved numbers but turns those cells into #NAME? the moment it recalculates. Resolving rewrites them as ordinary A1 references so Excel can recompute the model. Leave it off when the file is coming back here — the named form is readable and survives rows moving.

The result carries a link to the workbook rather than its bytes, so the host can offer the human the file without any of it passing through your context.

Return the workbook as base64-encoded .xlsx bytes.

Last resort. The bytes land in your context and cost roughly 1.4 KB of text per KB of file. Prefer save_workbook, which writes a real file and hands the host a link to it — the host can give the human the workbook without any of it passing through you.

Orient yourself in a workbook: every sheet, every block, and for each block the fields you can reference. One call is enough to start writing formulas.

Per block you get its ref name (BLOCKREF's first argument), its fields in column order (the third argument), key_field — the column whose values BLOCKREF matches as its second argument — and derived_fields, which are computed by a rule and reject writes.

Use describe_block when you need a field's actual rule, or the row keys and values. next_block_start clears everything already on the sheet, blocks and loose cell content alike, so passing it as create_block's position will not land on top of data.

Omit sheet to scan the whole workbook; passing it restricts to one sheet.

Return a block's full structure for the LLM: identity (name, sheet, position), per-field schema, and row keys in order. Every field reports both what it IS — type, description, required, unique, default_value, and references for a field pointing at another block — and what currently guards it: the value_formula, validation and editability templates. All of it comes from the Rust schema, the engine's authoritative source, so the answer is the same in every host and survives a save/load.

Read a field's type and description BEFORE writing a value to it: the description is where the unit, the convention, or the thing-not-to-do is written down, and it is the only record of it. A type of null means nobody has claimed one yet.

analyzes and analyzed_by say whether this block is a table or a conclusion drawn from one. A block with analyzes set is an ANALYSIS block — a total row, a set of statistics, a pivot — and its rows are its own, not the source's. Never sum an analysis block alongside the block it analyses: that counts the same numbers twice. A field with aggregates set is engine-computed from the source; writes to it are dropped, and you change it by changing the declaration.

Pass include_rows: true to additionally include current cell values as rows[].values[fieldName]. Off by default to save tokens — use it when the agent actually needs to inspect data, not when it only needs the shape.

Evaluate an Excel-style formula in a private scratch cell and return the computed value. Nothing is written to user-visible cells. Returns {type, value} where type is one of:

• "number" — value is a JS number

• "str" — value is a string

• "bool" — value is a JS boolean

• "error" — value is the Excel error code (e.g. "#REF!", "#NAME?")

• "empty" — value is null (formula returned an empty cell)

Use for:

• Quick checks: "=SUMIFS(OrderStatus, "amount", "*")" → total

• Sanity-test a candidate template before set_field_rule

• BLOCKREF / BLOCKREFS lookups against any block in the workbook

Leading "=" is optional — it is added automatically if missing.

Create a structured block (table) on a sheet. fields[0] is the row-key column — the value BLOCKREF matches on, so it has to be unique per record; it is ordinary data you can write. Block ref name (name) is used as the first arg to BLOCKREF/BLOCKREFS in formulas.

Field types supported:

• 'string' / 'number' — plain text/numeric cells.

• 'boolean' — cell stores 0/1 or TRUE/FALSE; UI renders ✅/❌ if host has the widget set.

• 'enum' (+ enum_id) — cell stores variant id; UI renders dropdown if host has the widget set. Watson auto-injects a variant-whitelist validation formula on the field so out-of-set writes light up as warnings even without widget rendering. Requires a prior define_enum_set call with matching id.

Rules (value_formula / validation / editability) are set separately via set_field_rule — this call only declares structure + initial rows. Auto-creates the target sheet if missing.

Turn a table that already exists in ordinary cells into a block, in place, without touching its values.

This is how you adopt a workbook someone hands you. create_block is for new tables and refuses to write over existing data; this one takes the data as it stands and gives it a name, fields and row keys, so you can address it as (block, row_key, field) and reference it from formulas by name instead of by coordinate.

Give position and the counts for the DATA only, leaving out any header row. Field names come from the header row — pass header_row, or leave it out and the row directly above the data is used when it looks like titles. fields states them outright instead.

The row key is inferred: the first column whose values are all present and all different. Pass key_field to choose. Whatever is inferred is reported back, so check it — the key is how formulas and later edits name a row.

Converting is a one-time cost: the block and its schema survive saving and reloading, and afterwards the region behaves exactly like one created as a block.

Write what a block is for, in prose, onto the block itself. Saved in the file and returned by describe_block, so it is how the next agent — or the next you, in a later session — learns what the table means. Say what one row represents, what any non-obvious field holds, and anything that must not be done to it. Do not restate the field names; they are already visible. Refused when the block reserves modifyDescription to its owner. Pass an empty string to clear it.

Add rows to an existing block. Appends at the end by default; pass after_key or before_key to insert at a position instead. Each row needs a key; values is an object keyed by field name. Fields with a value_formula are auto-materialized by the engine — don't pass them in values. Validation/editability shadows for the new rows are auto-installed by the engine at InsertRowsInBlock time, so no follow-up is needed. Also inserts the matching sheet rows (one block per sheet-row assumption — extends the sheet so downstream rows shift down).

Delete rows from a block by their key. Missing keys are silently ignored. Also deletes the matching sheet rows (one block per sheet-row assumption). If you try to delete every row, the last one is kept and its cells are cleared instead — the engine doesn't allow rowCnt=0 blocks.

Reorder a block by moving one row to a new position, addressing both the row and its destination by key. Moves to the end when neither after_key nor before_key is given (same default as add_block_rows). Row order inside a block is presentation only — formulas address rows by key, so reordering never changes a single computed value. Use it to match a reading order someone expects, not to change the model.

Write one or more cells inside any block(s) in a single atomic transaction. Each change addresses a cell by (block ref name, row_key, field) — the LLM never deals with raw (sheet, row, col).

Pass changes as an array; one-cell writes are just length-1 arrays. Batching is the cheap default — putting N writes in one call is one transaction, one calc pass, one undo entry.

Rejected up-front (whole tx aborts) when any change:

• targets a non-existent block / row_key / field, or

• targets a field with a value_formula on its schema (engine-computed; use set_field_rule to change the rule instead).

Value can be a literal (string / number / boolean) or a formula prefixed with '='. null clears the cell.

Attach declarative rules to a field. All three rule kinds (value_formula, validation, editability) are optional — pass only the ones you want to change. Omit a kind entirely to leave it untouched on this field; pass null to explicitly clear an existing rule.

Placeholders supported in formulas: #FIELD("name") — the same row's cell in field "name" #FIELD("name", "key") — field "name" on the row carrying that key, in THIS SAME block #KEY — the row's key value (quoted as a string literal) #PLACEHOLDER — the cell itself (validation/editability only)

The two-argument #FIELD is the only way to reach another row of the cell's own block: BLOCKREF is refused there (it depends on the whole-block vertex, so it would close a cycle). Use it for share-of-total or index-to-a-base-row columns, e.g. "=#FIELD("amt")/#FIELD("amt","TOTAL")". The other row is named by KEY, never by position — there is no "previous row" form, because rows can be reordered and inserted into, so a positional address would silently come to mean a different row. A running total (each row reading the row above) therefore has no rule form; write that column as ordinary cells outside the block. A rule that resolves onto the cell it is defining is rejected, as is a plain coordinate (A1/C3) landing inside the block — in a template a coordinate does not shift per row, so on the first row it would point at the cell being defined.

Engine behaviour after this call:

• value_formula → cells in the field become engine-computed (no direct writes). Every row's formula is re-materialized.

• validation → a ShadowKind::Validation shadow is auto-installed on every row; warning markers refresh.

• editability → a ShadowKind::UserEditable shadow is auto-installed on every row; the host permission patch reads it to gate writes.

Leading "=" on the formula body is optional; omit or include either way.

Add a block that analyses another one — a totals row, sitting directly below the table it summarises.

It is an ordinary block that declares which block it analyses, so its result is addressable like any other: BLOCKREF("<name>", "<label>", "<field>"). That is the point of it being separate — a total you can only look at is much less useful than one you can reference.

What the engine does with the declaration: it GENERATES each field's formula from it, so renaming a field of the source rebuilds the total instead of breaking it, and the total tracks the source as rows are added. Do not write the formulas yourself.

By default every number field of the source gets a SUM and everything else is left blank; pass aggregates to choose. Removing the source removes this block with it.

Read it back with describe_block: the analysis reports analyzes, the source reports analyzed_by. Never sum an analysis block alongside its source — that counts the same numbers twice.

Change what an existing analysis block computes: which of the source's fields it aggregates, with which function, and the label its row is addressed by.

Use this to arrive at an analysis in STEPS. Summing every number is often nearly right and wrong in one column — a rate wants AVERAGE, a text column wants COUNTA, an id column wants nothing at all. Adjust rather than rebuild: the block keeps its ref name, so formulas pointing at it keep working, and it is one undo.

aggregates REPLACES the set outright — a field you leave out stops being computed and its cell goes blank. Read the current set from describe_block first if you mean to add to it.

This is the simple kind of analysis: one row, one number per column. For one number per GROUP, use build__create_pivot / build__edit_pivot instead.

Cross-tabulate a table: one row per distinct value of rows, one column per distinct value of columns, each cell aggregating measure.

The result is an ordinary block, so every cell is addressable: BLOCKREF("<name>", "<a rows value>", "<a columns value>"). That is what lets you put one number from it in a sentence or feed it to another calculation.

You declare the recipe; the engine generates every cell from it. Do not write formulas, and do not write into the block — renaming a field of the source rebuilds the pivot rather than breaking it, which is only true because nothing is hand-written.

rows and columns must be fields whose values REPEAT (a region, a quarter, a status). Pointing either at an id gives one row per record, which is the source table again, not a pivot.

IMPORTANT: a pivot's numbers are live but its SHAPE is not. When new values appear in the source, its rows and columns fall behind while every number in it stays correct — call build__refresh_pivot. describe_block reports when that has happened.

Change an existing pivot's recipe — what it groups by, what it measures, how, in what order, over which records — and reshape it to match.

Use this rather than deleting and recreating: the block keeps its ref name, so every formula pointing at it keeps working, and the whole change is one undo.

This is also the way to REPAIR a pivot whose recipe stopped resolving (describe_block reports pivot_is_broken) — for instance after a source field was renamed. A broken pivot reads 0 in every cell rather than erroring, so it must be fixed, not refreshed: a refresh fails the same way.

Everything you omit is UNCHANGED. What you pass replaces that part outright — filters: [] clears the filters, columns: null turns a cross-tab into a simple group-by.

Bring a pivot's rows and columns back in line with its source.

Its NUMBERS were never stale — they are live formulas. Only the set of rows and columns falls behind, because no formula can add a row. That is exactly why this matters: a stale pivot shows correct numbers with whole groups missing, and totals taken from it are short with nothing to say so.

Call it before reading or reporting a pivot that describe_block flagged. Safe and cheap to call when nothing has changed — it reports that it did nothing.

Create a new sheet in the workbook. Returns the new sheet index. Idempotent: if a sheet with the same name exists, returns its index without creating a duplicate. Typically the agent does NOT call this directly — create_block will call it implicitly when the target sheet is missing. Use it only when you want an empty named sheet up front.

Read the values (and formulas) in a rectangular range of cells, addressed by zero-based (sheetIdx, startRow, startCol, endRow, endCol). Returns only the non-empty cells, each with its A1 ref, value, and formula (if any). Use this for ordinary "what is in these cells" questions; for a single computed result you can also use build eval_formula. Reads at most 500 cells per call — narrow the range if it is bigger.

Write one or more arbitrary cells on a sheet in a single atomic transaction (one undo step). Each cell is addressed by zero-based row/col. Content is a literal (string / number / boolean) or a formula prefixed with '='. null or '' clears the cell. For cells that belong to a block, prefer edit set_block_cells (it respects the schema); use this for plain, non-block cells. At most 200 cells per call.

Scan validation shadow cells and return every cell whose validation formula currently evaluates FALSE. Validation is advisory — the cell still holds its value, but the host UI renders a warning marker and you should treat it as "something the user/AI got wrong".

A field's rule is what its DECLARATION implies — required, unique, enum membership, reference existence — ANDed with whatever rule its author wrote. rule in the output names the declaration rather than quoting the generated formula, because the generated one is not something anyone typed. So a field with no rule text of its own can still appear here, which is the point: before the engine derived these, a required-but-empty cell raised nothing at all.

Also returns duplicate_keys: blocks where two records carry the same row key. That is not an advisory rule but a broken address — BLOCKREF resolves a key to the FIRST matching record, so the others are unreachable and every aggregate over the block double-counts, silently and without an error anywhere. The engine refuses to create a duplicate, so anything reported here came in with the file. Fix it by giving one of the records a distinct key before trusting any total over that block.

Also returns pivots_needing_attention. A pivot fails in a way no validation rule can see: stale means its numbers are each correct while whole groups are MISSING, and broken means its recipe stopped resolving so every cell reads 0 rather than erroring. Neither shows up as a red cell anywhere. Treat a broken pivot's numbers as unusable and fix the recipe; refresh a stale one before quoting any total from it.

Use this when answering 'why is something red?', 'what's broken after my last edit?', or before quoting any number you did not just compute yourself. It is the one call that answers 'is anything here untrustworthy' — the alternative is describe_block on every block, which is easy to skip and easy to forget.

Filters compose: omit both block and sheet to scan the whole workbook; pass either to narrow.

Pull-based on purpose: the LLM is turn-based, polling at decision points is cheaper than maintaining a live subscription. The host UI has its own per-cell push subscription for canvas warning markers.

Dry-run edits on the workbook's temp branch and report what they would do. Nothing is committed — the branch is discarded, so this is the safe way to explore a model instead of changing it and putting it back.

Two shapes. changes runs one hypothetical and returns every cell that would move, direct writes and cascaded recalculations alike. scenarios runs several, each on its own branch, and returns one result per scenario in order — that is a sensitivity table or a scenario comparison in a single call.

Add watch to get just the cells you care about instead of the whole cascade. A grid of sixteen scenarios over a model that cascades into 26 cells is 416 rows of diff to answer sixteen questions; watch makes it sixteen numbers. Name a cell semantically ({block, row_key, field}) or by coordinate ({sheet_idx, row, col}).

Follow a cell's dependencies, in either direction, using the engine's own dependency graph.

• precedents — what this cell reads. Use it to audit a number: "why is value-per-share what it is".

• dependents — what reads this cell, and through which reference. Use it before changing something: "what breaks if I edit this assumption".

Both by default. Name the cell semantically as (block, row_key, field), or by coordinate as (row, col) with an optional sheet_idx. Results come back named the same way whenever the cell sits inside a block, so you get "assumptions.wacc" rather than a coordinate to interpret.

This asks the engine rather than reading formula text, so it sees through BLOCKREF, ranges and whole-column references, and it answers the reverse direction — which formula strings cannot.

Granularity matters when blocks are involved. The engine tracks block dependencies per (block, field), not per row, so dependents of one block cell is everything reading that FIELD — the queried row among them. Each edge carries scope: "cell" is exact, "field" and "block" are over-approximations, and approximate: true is set on the result when any edge is wider than a cell. Treat a field-wide answer as "at least these", not "exactly these".

Find the input value that makes a chosen output equal a target — "what discount rate gives a value per share of 30".

Runs entirely on the engine's temp branch, so the workbook is never modified: this is a question, not an edit. The search happens inside the engine rather than as a conversation, so it costs one tool call instead of one per iteration.

Name both cells semantically as (block, row_key, field) or by coordinate as (row, col). Give between when you know a bracket; otherwise it expands outward from the current input value to find one.

Bisection, so it needs the output to move monotonically between the bracket ends and it finds one crossing. If the bracket does not straddle the target it says so rather than returning a number — a non-answer you can act on beats a plausible one you cannot.

Chart a block by naming its fields, instead of working out which cells they occupy. The chart stays bound to the block: it plots whatever the named fields hold, so records added to the block later appear on their own and inserting rows or columns cannot leave it pointing at the wrong cells. A col-schema block works the same way as a row-schema one. Use edit__describe_block or inspect first if you do not know the field names. Blocks with a "random" schema have no field axis and cannot be charted this way — chart their cell range with chart__insert instead. Fields are held by name. Renaming one breaks the link (the series goes empty); moving its column does not.

Insert a chart that reads its values live from the given ranges — editing those cells later updates the chart. Look at the data first so the series are right: a column of labels belongs in categoriesRef, each column of numbers is one series, and its header is that series' name. References are A1 (B2:B10, or Sheet2!B2:B10 to read another sheet). The chart is placed below the data unless anchor says otherwise.

List the charts on a sheet — id, kind, title, the ranges each series reads, and where the chart sits. Call this before updating or deleting one.

Reconfigure an existing chart in place, keeping its position. Anything left out keeps its current value; an empty string clears a text field (title, axis title, number format). Get the chart_id from chart__list first.

Delete a chart. Get the chart_id from chart__list. Undoable, but it removes the chart and its formatting.