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 (name, position, value_formula, validation, editability rules — all from the Rust schema, the engine's authoritative source), and row keys in order.

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, "金额", "*")" → 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 (always read-only). 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, then either header_row to read the field names from the titles or fields to state them. The first field is the row-key column, so put the column that identifies each record first.

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.

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.

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

Use this when answering 'why is something red?', 'what's broken after my last edit?', or before committing a multi-step build that depends on existing constraints.

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.