An MCP server that gives an agent a real, Excel-compatible spreadsheet engine with named-table blocks, formulas, validation, and analysis tools, and hands back genuine .xlsx files.
Workbook management — open a fresh workbook or load an existing .xlsx from disk or base64, save a real .xlsx (optionally resolving block references to plain A1 formulas for Excel), and export the file as base64.
Structured blocks instead of raw coordinates — create named tables, convert existing cell ranges into blocks, and address data by (block, row_key, field) rather than cell positions.
Row and cell editing — add, delete, reorder, and update block rows; write cells atomically in batches with formulas, literals, or cell clearing.
Column-level formulas and rules — define a formula once for a whole field, plus validation and editability rules, using Excel-compatible formulas with BLOCKREF and #FIELD references.
Adopting existing spreadsheets — turn a table someone already built in ordinary cells into a named, addressable block in place.
Analysis and exploration — evaluate formulas in scratch cells, trace precedents/dependents through the dependency graph, find what breaks before editing, and list validation violations.
What-if and inverse solving — dry-run one edit or a whole grid of scenarios in a single call on a temporary branch, and use goal seek to find the input that makes an output hit a target without modifying the workbook.
Raw-cell escape hatch — read and write arbitrary unstructured cells directly for data that doesn't fit a block.
Persistent session state — one active workbook lives across tool calls, so it acts as memory rather than a stateless calculator.
Runs locally with no network — stdio-based MCP server that can even run on an air-gapped machine.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@logisheets-mcp Create a 'MonthlySales' block with rows for Jan–Mar, add a total column as =units*price, and save it to sales.xlsx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A real spreadsheet engine your agent can think in. Excel-compatible formulas
it doesn't have to do in its head, a table it addresses by name instead of by
coordinate, and a genuine .xlsx at the end that a person can open, audit and
keep using.
An MCP server over LogiSheets, a spreadsheet engine written in Rust. MIT, runs on your machine, opens no sockets.
Ask a model for a five-year projection and it writes twenty formulas, each with
the row number adjusted by hand. That is where the silent mistake lives: one of
them reads B7 where it meant B8, the total looks plausible, and nothing
raises an error.
Then the sheet moves. Someone inserts a row at the top, deletes a year, adds a column. Every coordinate the model was holding is now off by one and it has no way to notice, so it spends the next turns re-reading cells to work out where things went instead of on the question you asked.
And every "what if" costs a round trip — write the input, recalculate, read the output, put it back. Sixteen scenarios is sixteen of those, and a scan that dies half way leaves a scenario behind in your model.
Related MCP server: Excel MCP Server
A block is a named table on the sheet. Rows have keys, columns have names, and everything is addressed by those rather than by position.
A field's formula is stated once, for the whole column — not per cell. Add a row and it computes. There is no twentieth formula to get wrong.
A reference names what it means: the pv field of the row keyed Y3.
Insert a row above it and the reference still says the same thing, because it
never said "row 8".
The engine owns computed values. A formula field cannot be overwritten with a number the model worked out itself.
create_block proj fields: year, fcf, df, pv
set_field_rule proj.pv = fcf × df ← once, for the column
add_block_rows Y1 … Y5
describe_block proj
→ Y1 147.2727 Y2 144.5950 Y3 141.9660 Y4 139.3848 Y5 136.8506
… the sheet is then reshaped: two rows inserted at the top, a column at the left …
describe_block proj
→ Y3 141.9660 ← same answer, same address, nothing re-derivedBlocks are created by the agent as it works, so nothing needs preparing. Point it
at a blank workbook or at a spreadsheet someone emailed you — convert_to_block
adopts a table that is already in ordinary cells, reading the field names off the
header row and working out which column is the key.
The conversation that builds a spreadsheet is almost never the conversation that has to answer a question about it. A week later there is a new session, with none of the context, holding only the file — and what the file records is what that session can know.
A grid records coordinates. =B11*$B$3*(1-$B$4) is correct and means nothing
until the agent fetches the label column and infers that A3 describes B3.
The schema is where the meaning goes instead, and it is written into the
.xlsx: field names, the key column, which fields the engine computes, and the
rule behind each one. One list_blocks call and the workbook introduces itself;
one describe_block and the rules come back as
#FIELD("revenue")*BLOCKREF("assum","margin","v") — an explanation rather than
a second lookup problem.
The schema still only says what shape the records are. What they mean is
prose, so a block carries a description: a sentence or two on create_block, or
set_block_description for a table adopted later, saying what one row is, what
the non-obvious fields hold, and what a later reader must not touch. It is
stored in the file and comes back from describe_block, which is the difference
between the next session reading the intent and inferring it from column names.
src/cold-read.test.ts pins that down rather than
asserting it. It builds a model in one session, saves it, and reopens the file
in a second session sharing nothing with the first — own server, own workbook,
no memory. Then: list_blocks recovers every block's fields, key field,
computed fields and row count in one call; every returned rule is checked to
contain #FIELD or BLOCKREF and no A1 coordinate at all; the fresh
session writes a BLOCKREF formula from orientation alone and the engine agrees
with arithmetic done independently in the test; and trace names what reads an
assumption before anyone edits it. Cost is metered on the wire, over the same
text a host shows the model: 540 B for a five-row model, 545 B for a
hundred-and-five-row one, one call each. Reading a schema is O(columns);
reading a grid to understand it is O(cells). Asking for the data still costs
what the data costs — 11 kB for those 105 rows — and the point is that the
second session gets to choose.
Longer version, with the reasoning: docs/the-second-session.md.
An agent asked for a chart usually renders an image. The image is right once, and then the human changes an assumption and it is a picture of a number that is no longer true.
chart_from_block writes a chart into the workbook instead, and a chart there
stores references, never values:
chart_from_block rev value_fields: q1, q2 category_field: region
→ <c:val><c:numRef><c:f>Rev!$B$1:$B$3</c:f></c:numRef>That is a native Excel c:chartSpace in the saved .xlsx — the same object
Excel writes itself. Edit a source cell and the chart follows, in Excel or here.
Add a region to the block and it appears in the chart on its own, because the
series is bound to the field, not to the cells the field happened to occupy
when the chart was made: inserting rows or columns cannot leave it pointing
somewhere wrong. chart_insert does the same for arbitrary A1 ranges, for data
that never became a block.
src/agent-loop.test.ts asserts this from the file's
bytes rather than from the tool's return value: build a block, chart it, save,
unzip the .xlsx and check that the chart part exists and that its series are
<c:f> references into the sheet.
Measured, not asserted. Against the two other MCP servers that work on a local
.xlsx — spreadsheet-kit 0.11.1,
which has its own Rust recalc engine, and
excel-mcp-server 0.1.8, the
most-installed one, on openpyxl:
this | spreadsheet-kit | excel-mcp-server | |
Write a formula, read its value | 30 | 30 |
|
Five-year DCF, value per share | 20.803603 · 15 calls | 20.803603 · 6 calls | formula text |
4×4 sensitivity, 16 answers | 1 call, 950 B | 16 calls, 1245 B | can't |
Solve backwards for an input | 1 call, 202 B | 18 calls, 1399 B | can't |
Reopen it later and explain it | 4 calls, 2.4 kB | 5 calls, 21 kB | 2 calls, 24 kB |
Answer again after the shape changed | 19.383943 |
| formula text |
Keep a handed-over file's features | 8 of 8 | 8 of 8 | 8 of 8 |
Reproduce it — one file per task, and each one runs all three servers:
npm run build # ours is driven as dist/cli.js
python3 bench/t1_compute.py # bench/t*.pyThe other two contestants have to be reachable first: spreadsheet-kit as an
amd64 Docker image, excel-mcp-server in a virtualenv at $BENCH_WORK/.venv
(default /tmp/bench-work). See bench/contestants.py
for exactly how each is started.
The tasks were committed before any other server's tool list was read
(bench/TASKS.md), every expected value is derived
independently in Python rather than read off a server's output, and tasks we
expected to lose are in the list on purpose.
Three caveats, so the table is not read for more than it says. "=SUM(A1:A2)" is
not a bug: openpyxl stores formulas without evaluating them, so that server
writes correct models but cannot answer a question about one. spreadsheet-kit is
a genuine peer, correct on everything it can attempt, and builds the model in
fewer calls than we do — our extra calls declare a schema, which is the trade
that pays off in the rows below. And on the reading row each server was reading
back a file it wrote, so only half of that margin transfers to a spreadsheet
that came from a person. The last row started at 0 of 8; writing the task is what
found that saves were dropping everything the engine had no opinion about.
Requires Node 20+.
npm install -g logisheets-mcpFor Claude Desktop, add to claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json; Windows:
%APPDATA%\Claude\claude_desktop_config.json), then restart:
{
"mcpServers": {
"logisheets": {
"command": "npx",
"args": ["-y", "logisheets-mcp"]
}
}
}Any MCP host that spawns a stdio server works the same way — Cursor reads the
same block from ~/.cursor/mcp.json.
Build me a three-year revenue model: 100 units at $9.50 growing 40% a year, with a 30% cost of goods. Then save it to ~/model.xlsx.
The numbers come back from the engine rather than from the model's guesses, and
the .xlsx has live formulas in it — change an assumption in Excel and watch it
recompute. To see the same thing with no LLM involved,
npm run build && npm run demo drives the real server over stdio and checks
every claim as it goes.
Twenty-six by default. Tool-selection accuracy falls as the list grows and every description costs context on every turn.
Tool | What it does |
| Start a fresh workbook, or load an existing |
| Write a real |
| The file as base64, for hosts with no shared filesystem. |
| Every sheet and block, plus where the next block should go. |
| A block's schema, keys, field rules, description, and optionally its values. |
| Evaluate a formula and return the value. Nothing is stored. |
| Create a named table. First field is the row key. |
| Adopt a table that is already in ordinary cells, in place. |
| Write what a block is for, in prose, into the file. |
| Add records — at the end, or |
| Remove records. |
| Reorder rows by key. Presentation only: no value changes. |
| Write cells by |
| Give a field a formula, a validation rule, or an editability rule. |
| Which cells break their field's validation rule, and why. |
| What edits would do, without doing them — one hypothetical, or a whole grid of scenarios in a single call. |
| What a cell reads, and what reads it, from the dependency graph. |
| What input makes an output hit a target. Searches inside the engine. |
| Add a sheet. |
| Chart a block by naming its fields. Follows rows added later. |
| Chart arbitrary A1 ranges — the raw-cell counterpart. |
| The charts on a sheet: type, title, and the ranges each series reads. |
| Reconfigure a chart in place — type, series, axes, labels. |
| Remove a chart. |
| Raw-cell escape hatch for data with no structure. |
Formulas are Excel-compatible plus BLOCKREF(block, key, field) for reading a
block cell by name. Inside a field rule, #FIELD("name") is the same row's
sibling and #FIELD("name", "key") is another row of the same block — the row
carrying that key, never a positional offset.
preview_changes and goal_seek are the two that change how a model gets
explored: each scenario runs on its own temp branch and is discarded, so a 4×4
sensitivity grid is one call returning sixteen numbers with nothing written to
the workbook, and an inverse solve is one call rather than one per bisection
step. trace answers the question formula text cannot — not what a cell reads,
but what reads it, which is what you want before touching an assumption.
Set LOGISHEETS_MCP_TOOLS=full for 64: undo/redo, formatting, merges, comments,
checkpoints, block move/resize, cross-block links, block permissions,
chart_suggest, raw row/column structure. Mutating tools carry MCP's
readOnlyHint / destructiveHint annotations so a host can gate them behind
approval.
Chart tools keep a namespace prefix where every other tool drops one. Inside
their namespace they are called list, insert, update and delete, and a
bare delete sitting next to delete_rows and delete_block_rows is a coin
flip for the model — which is the cost this whole section exists to avoid.
save_workbook writes a real .xlsx and returns an MCP resource link — a
uri, media type and size — rather than the bytes, which would cost ~280 KB of
context for a 200 KB workbook and teach the model nothing. Hosts that want the
file read it from workbook://current.xlsx; export_xlsx returns base64 for
hosts implementing no resources at all.
Formulas can be written out as BLOCKREF("proj","Y3","pv") for a person to read,
or resolved to plain coordinates for Excel to chew on.
One MCP session holds one active workbook, alive across tool calls — that persistence is what makes it memory rather than a calculator.
Reads and writes go wherever the server process can reach, which is normal for a local stdio server and the same posture as the official filesystem server. Run it as a user with only the access you intend it to have.
No sockets, no ports, no telemetry. Your host spawns this as a child process and
they exchange newline-delimited JSON-RPC over stdin and stdout; the engine is
WASM in that same process, so a formula is a function call rather than a request.
An air-gapped machine is a supported way to run this. Checked rather than
asserted: after a full session — create a block, attach a field rule, evaluate a
formula, save an .xlsx — the process holds six pipes and no sockets, on no
listening port.
A thin shell over three LogiSheets packages:
logisheets-runtime (the
headless engine), logisheets-logician (the tool definitions), and the
Rust/WASM core.
npm install && npm testTo work on the engine at the same time, check out
LogiSheets as a sibling directory, build
its packages, and run npm run link:local — that symlinks the three into
node_modules so local engine changes take effect without reinstalling. Re-run
it after any npm install.
To use it as a library, createServer returns the MCP Server, the
WorkbookSession and the tool map, so you can host it over any transport:
import {createServer} from 'logisheets-mcp'
const {server, session, tools} = createServer({mode: 'full'})MIT. Part of the LogiSheets project.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | ||
| block | Yes | Block ref name. | |
| after_key | No | Insert directly after the row with this key, instead of appending at the end. Mutually exclusive with before_key. | |
| before_key | No | Insert directly before the row with this key. Use the first key to insert at the top. Mutually exclusive with after_key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: auto-materialization of value_formula fields, auto-installation of validation/editability shadows, and the side effect of inserting sheet rows that shift downstream rows. These are significant behavioral details not captured in the schema or annotations, fully meeting the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, covering all essential aspects in three sentences. It front-loads the core purpose and then logically proceeds to positioning, key requirements, engine behavior, and side effects. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, no output schema), the description is thorough: it explains default behavior, alternate insertion modes, value constraints, automatic shadow installation, and sheet row impact. The only minor omission is a stated return value, but that is not critical for a write operation and is not required since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the description adds value by clarifying that rows require a key and values are keyed by field name—though this partly repeats schema. The crucial addition is the caution about value_formula fields ('don't pass them in values'), which is not in the schema. This elevates understanding of the values parameter beyond the basic schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add rows to an existing block' – a specific verb (add) + resource (block) that clearly distinguishes from siblings like delete_block_rows and move_block_row. It also explains the default append behavior and positional insertion via after_key/before_key, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical guidance: append is default, insertion can be placed with after_key/before_key, and value_formula fields should be omitted. However, it does not explicitly contrast with alternative tools (e.g., set_block_cells) or state when not to use this tool, so it falls short of perfect guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chart. Get the chart_id from chart__list. Undoable, but it removes the chart and its formatting.
| Name | Required | Description | Default |
|---|---|---|---|
| chartId | Yes | From chart__list. | |
| sheetIdx | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the agent knows this is destructive. The description adds that it is 'Undoable' but removes the chart and its formatting, providing extra context about reversibility and side effects. This goes beyond the annotations and adds value without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero fluff. The action is front-loaded, and the prerequisite instruction is directly relevant. No redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description covers the main intent and the chartId source, but it fails to explain the sheetIdx parameter, which is required. No output schema exists, so return behavior is not specified, but that might be acceptable for a delete operation. The missing sheetIdx explanation is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: only chartId has a description ('From chart__list'), while sheetIdx has none. The description clarifies chartId by repeating the schema hint, but it offers no explanation for sheetIdx. Since half of the parameters are undocumented in both schema and description, the description only partially compensates for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action: 'Delete a chart.' This is specific to a chart resource and distinctly different from siblings like chart_insert, chart_list, chart_update, and chart_from_block. An agent can immediately identify this as the deletion operation without confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to 'Get the chart_id from chart__list,' which provides a clear prerequisite for usage. It doesn't explicitly mention alternatives or exclusions, but the context of deletion is unambiguous. It implies that chart_list should be used first, which is helpful guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Defaults to the block's schema name. | |
| anchor | No | Top-left cell of the chart. Defaults to two rows below the block. | |
| blockId | Yes | ||
| sheetIdx | Yes | Zero-based sheet index. | |
| chartType | No | Defaults to col. | |
| sizeInCells | No | ||
| valueFields | Yes | Field names to plot, one series each, in order. | |
| categoryField | No | Field whose values label the categories (the X axis). The block's key column is not addressable as a range, so name the field that reads as a label. Omitted, the categories are just 1..n. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses binding behavior beyond annotations: the chart stays bound to the block, updates with new records, survives column moves, but breaks if a field is renamed. Annotations only say readOnlyHint=false and destructiveHint=false, so this adds valuable context about how the chart behaves over time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph that leads with the core purpose, then adds behavioral detail, usage guidance, and a caveat – all in a logical order with no wasted words. Every sentence contributes distinct, actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description covers the key contextual aspects: what it does, how to prepare, when not to use it, and how the chart behaves. It also addresses schema variations (col vs. row) and the random-schema limitation, leaving nothing essential for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the baseline is 3. The description adds conceptual context about field-name binding that relates to valueFields and categoryField, but it does not systematically explain each parameter beyond what the schema already provides. It adds some value, but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 'Chart a block by naming its fields' – a concrete verb and resource. It also distinguishes itself from the sibling chart_insert by explicitly noting that random-schema blocks should use chart_insert instead, so an agent can tell them apart immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit prerequisites ('Use edit__describe_block or inspect first if you do not know the field names') and an explicit exclusion: 'Blocks with a random schema... cannot be charted this way — chart their cell range with chart__insert instead.' This leaves no ambiguity about when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Chart title. | |
| anchor | No | Top-left cell of the chart, e.g. 'H2'. Defaults to two rows below the data. | |
| series | Yes | One entry per data series. Each valueRef is an A1 range of the values to plot. | |
| sheetIdx | Yes | Sheet the chart is placed on (zero-based). | |
| chartType | Yes | col = vertical bars, bar = horizontal. pie/doughnut plot one series. scatter/bubble take numeric X from categoriesRef. stock needs 4 series (open/high/low/close) or 3 (high/low/close). surface plots a grid, one series per row. | |
| sizeInCells | No | Chart size in cells. Defaults to 15 × 8. | |
| categoriesRef | No | A1 range of the category labels (the X axis), e.g. A2:A10. For scatter/bubble these are the numeric X values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds key behavioral traits: the chart is live-linked to the ranges (editing cells updates the chart) and default placement below data. These are useful beyond the annotations, though it does not disclose behavior on invalid ranges or chart type constraints (which are in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. The core purpose is front-loaded, then data preparation guidance, then reference syntax and placement. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 7 parameters and nested objects, the description covers the most critical aspects: data mapping, references, and placement. It does not explain all chart type nuances (e.g., bubble sizeRef, combo seriesType), but those are documented in the schema. The essential guidance for correct invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant semantics beyond the schema. It explains the relationship between data columns and series/categoriesRef, gives A1 reference syntax including cross-sheet, and clarifies the default anchor placement. This is practical guidance an agent needs beyond raw parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (insert) and resource (a chart) and distinguishes its key feature: values read live from given ranges. It also explains the placement behavior. This is specific and distinguishes from siblings like chart_from_block, which would use a block rather than ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for how to use the tool: look at data first, map label column to categoriesRef, number columns to series, and use A1 references. It does not explicitly mention alternative tools like chart_from_block, but the live-range behavior implies when this tool is appropriate. No exclusions are given, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sheetIdx | Yes | Zero-based sheet index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description adds value by specifying the exact content returned (ranges, position). It implies no side effects beyond what annotations cover, and provides useful detail about the listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action, the resource, and the key details, followed by a usage hint. Every word earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, no output schema, and read-only annotations, the description provides enough information for an agent to call it correctly and understand the return fields. It lacks explicit mention of edge cases like empty sheets, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter sheetIdx is fully documented in the schema (100% coverage) with a clear description. The tool description adds no additional semantic detail about this parameter, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'charts on a sheet' and enumerates the returned fields (id, kind, title, ranges, position). This distinguishes it from sibling tools like chart_from_block or chart_update, making its function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call this before updating or deleting one,' giving a clear when-to-use directive. It does not name alternative tools or state when not to use it, but the guidance is actionable and context-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Empty string clears it. | |
| numFmt | No | Excel number-format code for the value axis and labels, e.g. "#,##0.00" or "0%". Empty falls back to the source cells' own format. | |
| series | No | One entry per data series. Each valueRef is an A1 range of the values to plot. | |
| chartId | Yes | From chart__list. | |
| stacked | No | Stack the series. Ignored by pie and scatter. | |
| sheetIdx | Yes | ||
| chartType | No | ||
| legendPos | No | ||
| catAxisTitle | No | ||
| valAxisScale | No | Replaces the whole value-axis scale — fields left out become automatic, which is how a fixed bound is cleared. | |
| valAxisTitle | No | ||
| categoriesRef | No | Re-point the category labels (A1 range). | |
| showDataLabels | No | Print each point's value next to it. | |
| showPercentLabels | No | Add the percentage to labels (pie-like charts). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical behavioral details beyond annotations: 'Anything left out keeps its current value' and 'an empty string clears a text field'. It also mentions position is kept. Annotations only indicate non-read-only and non-destructive, so the description carries the burden and fulfills it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core behavior, then the prerequisite. No wasted words; the most important operational detail (keep/clear behavior) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 14-parameter tool with nested objects, the description covers the key behavioral aspects that aren't in the schema. It explains the general update model, how to obtain the ID, and references the 'clearing' mechanism. No critical gaps remain for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 64%, so the description must compensate. It provides the overarching semantics: omitted fields retain current values, empty strings clear text fields, and valAxisScale replacement semantics are clarified. This goes beyond the schema's per-field descriptions and is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Reconfigure an existing chart in place') on a specific resource ('existing chart'), and distinguishes it from siblings by noting it keeps position. This clearly differentiates it from chart_insert (new) and chart_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to get chart_id from chart__list first, a clear prerequisite. It implies use only on existing charts, and the sibling list includes chart_insert for creation, so the when-to-use guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Ref name for the new block — BLOCKREF's first argument. Must be unique. | |
| sheet | Yes | Sheet the table is on. | |
| fields | No | Field names, when there is no header row. Length must equal col_count. | |
| position | Yes | Top-left cell of the data, excluding the header row. | |
| col_count | Yes | Number of columns. | |
| key_field | No | Which field identifies a row. Omit and the first column whose values are all present and all different is used. | |
| row_count | Yes | Number of data rows. | |
| header_row | No | Row holding the column titles; field names are read from it. Omit it and the row directly above `position` is used when it looks like a header — all text, over data that is not. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: it is in-place, does not alter values, the conversion is a one-time cost, the schema persists, and the row key inference is reported back. It does not mention potential error conditions or reversibility, but given the annotation coverage, it is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. It is somewhat lengthy but every sentence adds meaningful information about usage, parameter relationships, or persistence. It could be trimmed slightly, but it remains focused and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, nested objects, no output schema), the description is thorough. It covers the main use case, parameter semantics, inference behavior, and the fact that the inferred key is reported back. No critical information for invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema covers all parameters (100% coverage), the description adds substantial semantic value beyond the schema. It clarifies that position and counts refer to data only, explains the relationship between header_row and fields, and details how key_field inference works. This goes beyond simple parameter descriptions to explain how to use them together effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: turning an existing table into a block in place without altering values. It distinguishes itself from the sibling create_block by explicitly noting that create_block is for new tables and refuses to overwrite existing data, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool versus create_block: 'This is how you adopt a workbook someone hands you. create_block is for new tables and refuses to write over existing data.' It also explains the context of adopting existing data and how this tool fits the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Block ref name. Used as the first arg to BLOCKREF/BLOCKREFS in formulas. Must be unique within the workbook. | |
| sheet | Yes | Target sheet name. | |
| fields | Yes | Column definitions in order. fields[0] is the row-key column. | |
| position | Yes | Top-left cell of the block (0-indexed). | |
| description | No | What this table is for, in a sentence or two: what a row represents, what the fields mean where the names are not obvious, and anything a later reader must not do to it (e.g. a field the craft maintains). Saved with the block and returned by describe_block, so write it for whoever opens the file next rather than for this conversation. | |
| initial_rows | No | Optional initial rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it notes that fields[0] is always read-only, that enum validation is auto-injected, and that the call auto-creates the target sheet. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false) and appropriately discloses that it only declares structure and initial rows, not rules. This is valuable for the agent's understanding of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for field types and a separate note about rules. It front-loads the core purpose and keeps each sentence informative. While it is moderately long, it avoids fluff and each section serves a clear purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers most important context: structure, field type semantics, dependencies, and auto-creation. However, it fails to mention date/datetime as supported field types, which is a notable gap given the schema's enum includes them. This omission could lead to incorrect tool usage. Other aspects like return values are not described, but since there is no output schema and the tool is a creation operation, that is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented. The description adds meaning for enum_id (requires prior define_enum_set) and the row-key column, which is helpful. However, it lists supported field types as only string/number, boolean, and enum, omitting date and datetime that are present in the schema's enum. This omission could mislead an agent into thinking those types are unsupported, reducing the added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a structured block (table) on a sheet, specifies the row-key column behavior, and distinguishes itself from sibling tools like convert_to_block by emphasizing it creates a new block. The phrasing 'Create a structured block' is specific and action-oriented, leaving no ambiguity about the primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what this call does and does not do: it explicitly states that rules are set separately via set_field_rule, and it mentions auto-creating the sheet if missing. While it doesn't name alternative tools for different scenarios, it gives enough guidance on when to use this tool versus related ones by clarifying its scope (structure + initial rows only).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Sheet name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses idempotent behavior (returns existing index without duplicate), return value, and implicit invocation context. This adds significant behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: function, idempotency/return, and usage guidance. No redundant information, and it is well-structured with a clear sequence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is complete. It covers purpose, return value, idempotency, and when to call directly vs. implicitly. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter 'name' with a clear description ('Sheet name.'). The tool description does not add additional parameter semantics, but the schema already suffices, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a new sheet in the workbook' and mentions the return value (sheet index). It effectively distinguishes this from sibling tools like create_block by focusing on sheet creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: '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.' This clearly states when to use and when not to, and names the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | ||
| block | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds significant behavioral detail: missing keys are silently ignored, sheet rows are also deleted (with the assumption of one block per sheet-row), and the special behavior when deleting all rows (last row kept and cells cleared) explained by an engine constraint. This goes far beyond the annotations to disclose real-world behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, followed by key behavioral notes and an edge case. Every sentence contributes value without redundancy or fluff, making it optimally concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple params and no output schema, the description covers essential aspects: what it deletes, how deletion works (by key), side effects on sheet rows, and the critical edge case of deleting all rows. This is sufficient for an agent to understand scope and limitations without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (coverage 0%), so the description must supply meaning. It clarifies that 'keys' are row keys used to select rows for deletion, but does not explain the format or structure of these keys (e.g., whether they are numeric IDs or string labels). The 'block' parameter is only implied as the target block identifier, with no additional detail. The description adds some meaning but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete rows from a block by their key', specifying the action (delete), resource (block rows), and method (by key). This distinguishes it from siblings like add_block_rows, move_block_row, and set_block_cells, which perform different operations on block rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about side effects (deletes matching sheet rows) and an important edge case (keeps the last row when deleting all), which helps users understand when this tool is appropriate. However, it does not explicitly name alternative tools or state when not to use this tool, leaving the usage boundaries implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Block ref name (the `name` of create_block). | |
| include_rows | No | When true, include current cell values. Off by default to save tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context: it mentions the source is 'the Rust schema, the engine's authoritative source', and explains the default behavior of include_rows to save tokens. No contradictions or gaps in behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense. The first sentence encapsulates the core purpose, and the second paragraph efficiently explains an optional parameter with clear reasoning. No wasted words; each part contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (returns schema fields, validation, editability rules) and the absence of an output schema, the description fully covers what the agent can expect: identity, per-field schema details, row keys, and optional cell values. It also clarifies the default behavior, making it complete for the agent's decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are described in the schema. The description goes beyond by specifying the exact structure of the returned data (e.g., rows[].values[fieldName]) and explaining the token-saving rationale for include_rows, which adds meaningful semantic detail without repeating schema content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: returning a block's full structure including identity, per-field schema with detailed elements (name, position, value_formula, validation, editability rules), and row keys. It distinguishes itself from siblings like list_blocks (which likely only lists block names) and get_cells (which retrieves cell values) by emphasizing the structural/schema role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for the include_rows parameter ('Off by default to save tokens — use it when the agent actually needs to inspect data, not when it only needs the shape'), which helps decide when to set that flag. It does not explicitly contrast with alternative tools, but the purpose is clear enough to infer appropriate usage. A slight boost would come from naming specific alternatives, but the current guidance is practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| expr | Yes | Formula, with or without leading "=". E.g. "SUM(A1:A10)" or "=BLOCKREF(\"orders\", \"O001\", \"金额\")". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavior: private scratch cell execution, no writes to user-visible cells, automatic leading '=' insertion, and the full return type contract including error and empty cases. This exceeds what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear definition, a bulleted 'Use for' section, and a brief note about the leading '='. Every sentence adds useful information with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully documents the return value shape and all possible type values. It also covers safety, use cases, and syntax details, making it sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter expr is already well-documented in the schema with an example and the optional leading '=' note. The description adds further value by covering return types and BLOCKREF usage, but the schema already carries most of the parameter meaning, so this is strong but not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it evaluates an Excel-style formula in a private scratch cell and returns the computed value, which distinguishes it from mutation tools like set_cells or set_field_rule. The return format is also specified, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly lists concrete use cases: quick checks, sanity-testing templates before set_field_rule, and BLOCKREF/BLOCKREFS lookups. It also clarifies that nothing is written to user-visible cells, implying it should not be used for write operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds crucial behavioral context: the bytes are injected into the agent's context and cost roughly 1.4 KB of text per KB of file. This warns about significant resource consumption and explains why the sibling tool is preferred.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by a concise cost/alternative explanation. Every sentence carries essential information; there is zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description fully covers what the agent needs: what it returns, the cost to the agent, and when to use the sibling instead. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema leaves nothing undocumented. Per the rubric, 0 params gets a baseline of 4; the description adds no parameter-specific detail because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific, unambiguous purpose: 'Return the workbook as base64-encoded .xlsx bytes.' It clearly identifies the verb, resource, and output format, and distinguishes itself from sibling save_workbook by framing this as the 'last resort' option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when NOT to use it ('Last resort') and names the preferred alternative: 'Prefer `save_workbook`'. It explains the key tradeoff (bytes passing through context vs. real file+link), giving the agent actionable decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| endCol | Yes | Zero-based last column (inclusive). | |
| endRow | Yes | Zero-based last row (inclusive). | |
| sheetIdx | Yes | Zero-based sheet index. | |
| startCol | Yes | Zero-based first column. | |
| startRow | Yes | Zero-based first row. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description builds on that by adding key behaviors: returns only non-empty cells, includes A1 ref, value, and formula, and enforces a 500-cell per call limit. This is useful beyond the annotations, though it doesn't cover edge cases like error handling or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what the tool does, what it returns and how to use it, and the operational limit. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description adequately explains the return shape (non-empty cells with A1 ref, value, formula) and the 500-cell cap. It could mention behavior for out-of-range indices or fully empty ranges, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described as zero-based and inclusive. The description reiterates the parameter order but adds no new meaning beyond the schema, so the baseline score of 3 for high schema coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads values and formulas in a rectangular cell range, with a specific verb ('Read') and resource ('rectangular range of cells'). It also distinguishes itself from the sibling eval_formula by noting that for a single computed result you'd use that tool instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this for ordinary "what is in these cells" questions' and directs to eval_formula for a single computed result. This provides clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The value `target` should reach. | |
| set | Yes | The input cell to vary. | |
| target | Yes | The output cell to drive to `to`. | |
| between | No | Search bracket [low, high]. Omit to expand outward from the current input value. | |
| tolerance | No | How close to `to` counts as solved. Default 1e-6 relative. | |
| max_iterations | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond the readOnlyHint and destructiveHint annotations: it explains the temp-branch execution, the bisection algorithm, the monotonicity requirement, and the behavior when the bracket does not straddle (returns a non-answer). This is exactly the kind of context that helps an agent predict outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it starts with a clear purpose, then a short note on safety, then usage details, then algorithm behavior. Every sentence earns its place without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (goal seek with bisection, optional bracket, monotonicity assumption) and lack of an output schema, the description covers all essential aspects: purpose, non-destructive nature, cell naming, bracket behavior, monotonicity requirement, and failure handling. It is fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the baseline is 3. The description goes further by explaining the semantics of the `between` parameter (optional, expand outward if omitted) and how to name cells (semantic vs. coordinate). It clarifies the search process and the meaning of the bracket, adding value beyond the schema's short descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose precisely: 'Find the input value that makes a chosen output equal a target' with a concrete example. It distinguishes itself from sibling tools by framing it as a question rather than an edit, which is unique among the listed mutation/set tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to supply a bracket ('Give `between` when you know a bracket') and how to reference cells. It also explains why to use this over iterative conversation (one call vs. many). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds context about derived_fields rejecting writes and the orientation purpose, without contradicting annotations. It doesn't describe side effects, but annotations suffice; the added detail about returned data is a bonus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and returns a clear structure of paragraphs, but includes tangential information about next_block_start and create_block that isn't directly needed for using list_blocks. This slightly dilutes conciseness, though each sentence carries some value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one optional parameter and no output schema, the description adequately explains the tool's output: per block it returns ref name, fields, key_field, and derived_fields. It also points to describe_block for further details, making the tool self-contained for an agent to understand its output and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 0%, so the description is the sole source of meaning. It fully explains the sheet parameter: omitting it scans the whole workbook, passing it restricts to one sheet. This provides complete semantic clarity beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every sheet, every block, and the fields per block, with specific details about returned metadata (ref name, fields, key_field, derived_fields). It distinguishes itself from describe_block by positioning itself as a high-level orientation tool, so purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use guidance: use describe_block when needing field rules or row keys/values, and explains sheet parameter behavior (omit for whole workbook, pass for single sheet). This clearly differentiates usage from alternatives and gives contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| block | No | Block ref name. Omit to scan all blocks. | |
| limit | No | ||
| sheet | No | Sheet name. Omit to scan all sheets. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context about advisory semantics, host UI warning markers, and the pull-based polling rationale. However, the phrase 'return every cell' is slightly at odds with the `limit` parameter default of 50, so the limit's effect is not fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized into three short paragraphs: purpose, when-to-use, and filter/polling behavior. Every sentence contributes; the pull-based rationale is relevant for an LLM agent deciding whether to poll or rely on push.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage triggers, filter composition, advisory semantics, and polling rationale. Gaps remain around the exact return shape and how `limit` interacts with the 'every cell' promise, and there is no output schema to fill those gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 2/3 parameters (block and sheet) with descriptions; the description adds 'omit both... to scan the whole workbook; pass either to narrow,' clarifying filter composition. The `limit` parameter receives no additional semantics beyond the schema's default/minimum, and the 'every cell' wording makes the cap less clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Scan validation shadow cells and return every cell whose validation formula currently evaluates FALSE.' It clearly distinguishes this from sibling tools like get_cells or eval_formula by focusing specifically on validation failures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when answering why is something red?, what's broken after my last edit?, or before committing a multi-step build...' It also explains filter composition and how to omit or pass block/sheet to narrow the scan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Row key of the row to move. | |
| block | Yes | Block ref name. | |
| after_key | No | Land the row directly after the row with this key. Mutually exclusive with before_key. | |
| before_key | No | Land the row directly before the row with this key. Pass the first key to move it to the top. Mutually exclusive with after_key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: 'reordering never changes a single computed value' and 'presentation only'. This clarifies the actual impact of the operation beyond what annotations convey, helping the agent understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, purposeful sentences. The main action is front-loaded, the default behavior is stated in the second sentence, and the practical usage note is saved for the final sentence. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, default behavior, and the important nuance that reordering is presentation-only. This is complete for a simple reorder tool with a clear sibling group (add_block_rows, delete_block_rows) and no output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying the default behavior when neither after_key nor before_key is given ('Moves to the end') and by explaining that both row and destination are addressed by key. This is useful context not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Reorder a block by moving one row to a new position', which is a specific verb+resource action. It clearly distinguishes this from sibling tools like add_block_rows and delete_block_rows by focusing on reordering an existing row rather than adding or removing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use and when not to use: 'Use it to match a reading order someone expects, not to change the model.' It also explains the default behavior when neither after_key nor before_key is given and references the sibling add_block_rows for the same default, helping the agent choose between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | File name to report to the engine when loading from base64. | |
| path | No | Path to an existing .xlsx to load. Omit for an empty workbook. | |
| xlsx_base64 | No | A .xlsx as base64, for when no shared filesystem exists. Use `path` when you can. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing a key side effect: 'replaces whatever workbook the session currently holds, discarding unsaved changes.' It also provides actionable behavioral context about base64's enormous context cost, which is not captured in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. The description is front-loaded with the primary concept, then covers alternatives, timing, and parameter selection in a compact but complete way. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's stateful behavior and optional parameter combinations, the description fully covers the essential usage context: what the tool does, when not to call it, why the current workbook is replaced, and the preferred data-passing method. No output schema is needed for this simple initialization tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so a baseline score of 3 applies. The description additionally clarifies when to use path over xlsx_base64 and explains why, enriching parameter semantics without repeating the schema verbatim.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Start the workbook you will work in.' It further distinguishes its role by explaining fresh empty workbook vs loading an existing .xlsx, which is distinct from sibling tools like create_sheet or save_workbook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given for when to call ('once at the start, not between steps'), when not to call it ('you do NOT have to call it at all'), and which parameter to prefer ('Prefer path over xlsx_base64'). This is exemplary for helping an agent decide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}).
| Name | Required | Description | Default |
|---|---|---|---|
| watch | No | Report only these cells' values instead of the full diff. Name each one semantically or by coordinate. | |
| changes | No | One hypothetical. Use `scenarios` for more than one. | |
| scenarios | No | Several hypotheticals, each evaluated independently. Results come back in this order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false ya, but the description adds meaningful behavioral detail: writes go to a temp branch that is discarded, and it highlights a potential large-response performance pitfall (416 rows of diff). This is exactly the kind of context that helps an agent avoid surprises beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly-packed paragraphs, each earning its place: 1) core behavior and safety, 2) two modes, 3) output-size optimization. Front-loaded with the most important 'dry-run/safe' concept. No fluff, but the description is dense and requires some parsing; still efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 params and no output schema, the description covers the modes (`changes` vs `scenarios`), how to interpret results (returns what would move, including cascades), and the `watch` parameter's purpose and advantage. It doesn't describe the exact return shape, but given dense schema descriptions, this is sufficient and complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: `watch` says 'report only these cells' values instead of the full diff', `changes` 'one hypothetical... use `scenarios` for more', and each field has a description. The description complements it by explaining the semantic vs coordinate addressing for `watch` and the notion of 'cascaded recalculations' which clarifies that the diff includes more than direct writes. Builds on schema, adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource ('Dry-run edits on the workbook'), states what it reports (what they would do), and explicitly contrasts with actual changes ('Nothing is committed'). It clearly distinguishes two operational shapes (changes vs scenarios) and mentions the optional watch filter, all in the first sentence. This strongly separates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames this as 'the safe way to explore' instead of changing and putting it back, giving clear when-to-use context. It also explains when to use `watch` vs. getting the whole cascade incl. an explicit example of a large scenario grid. The schema reinforces with `scenarios` 'use `changes` for one.' Guidance is explicit and immediate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Destination .xlsx path. Defaults to the path the workbook was opened from. | |
| resolve_block_refs | No | Rewrite BLOCKREF/BLOCKREFS as ordinary A1 references. Set this when the human will open the file in Excel; Excel has no BLOCKREF function and would show #NAME? on recalculation. One-way: a resolved file is an export, not a round trip. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations being minimal, the description extensively discloses behavior: default path (opened from or last saved), what is saved (values, formulas, block structure), the BLOCKREF issue and one-way resolution, and the result carrying a link instead of bytes. This goes far beyond the annotations and provides critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured: purpose first, then defaults, then a critical warning about block refs, and result behavior. Every sentence contributes necessary information, but the length could be trimmed if some details were in schema or annotations. No wasted words, but not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a save operation with no output schema, the description covers all important aspects: destination, what data is persisted, Excel compatibility nuances, one-way export, and return format (link). It also implies the tool's role in the overall workflow. This is comprehensive for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described, but the description adds meaningful context: path defaults and when to set resolve_block_refs (Excel vs round-trip, one-way nature). This goes beyond the schema, so it earns above the baseline 3, though it doesn't introduce new parameter syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a workbook to a real .xlsx file for the human to open. It distinguishes from sibling tools by emphasizing 'real .xlsx file' and 'hand your work back', but does not explicitly differentiate from export_xlsx, so it lacks explicit sibling differentiation. Thus, it's clear but not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('do it when the task is done') and provides detailed guidance on when to set resolve_block_refs (for Excel vs round-trip). However, it does not mention when not to use it or alternatives like export_xlsx, so it lacks exclusions. This is clear context but with no explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds significant behavioral detail: the entire transaction aborts if any change targets a non-existent block/row/field or a value_formula field, and it clarifies that null clears a cell. It also mentions atomicity, single calc pass, and single undo entry—information beyond what annotations provide. This fully aligns with the annotations, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-organized paragraph that front-loads the main action, then covers batching, error conditions, and value types. There is no fluff or repetition; every sentence adds essential information, making it concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's complexity: atomic batch behavior, validation rules, value handling (literal, formula, null), and an explicit alternative for value_formula fields. With no output schema, this is adequate for a write operation, and the description leaves no critical gaps for an agent to discover at runtime.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has minimal descriptions (only the value parameter has a description), but the tool description compensates by explaining each parameter in prose: block ref name, row_key, field, and value semantics, including formula prefix and null clearing. It adds meaning beyond the basic types, though it could be more explicit about the format of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Write one or more cells inside any block(s) in a single atomic transaction.' It specifies the verb (write), resource (cells in blocks), and the addressing mechanism (block ref name, row_key, field), distinguishing it from raw cell operations. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (for block-based cell writes, never raw coordinates) and explicitly names an alternative (set_field_rule) for fields with value_formula. It also encourages batching as the default. However, it does not explicitly contrast with sibling tools like set_cells or mention cases where it should be avoided, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Block ref name. | |
| description | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds meaningful behavioral context: persistence ('Saved in the file'), the refusal condition, and the clearing behavior. It does not contradict annotations and covers the key side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized: the core action first, then purpose, then content guidance, then constraints. Every sentence contributes value without redundancy. It is appropriately detailed for the task.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers all necessary aspects: what to write, how to clear, and when it may fail. It leaves no critical ambiguity for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (name is documented, description is not). The description compensates thoroughly by explaining exactly what the description parameter should contain ('Say what one row represents... Do not restate the field names') and how to clear it. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Write what a block is for, in prose, onto the block itself.' It clearly distinguishes this from sibling tools by contrasting with describe_block (which reads) and by emphasizing the prose, non-field-name content. The action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to document a block for future agents) and includes a specific refusal condition ('Refused when the block reserves `modifyDescription` to its owner'). It also explains how to clear a description via empty string. It does not explicitly name alternatives beyond implying describe_block, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| cells | Yes | ||
| sheetIdx | Yes | Zero-based sheet index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: atomicity (one undo step), clearing cells with null/empty string, and the 200-cell limit. Given annotations already show mutability (readOnlyHint=false) and non-destructive (destructiveHint=false), the added details on clearing and atomicity add value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and each sentence serves a distinct function: purpose, addressing/content rules, usage preference, and limit. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, array of objects) and lack of output schema, the description covers essentials: how cells are addressed, content types, clearing, block preference, and call limit. It does not mention error handling or response format, but that is less critical for a write operation. The description is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'content' and 'row'/'col' descriptions are in schema; 'sheetIdx' and the array structure are not fully described). The description adds meaning about cell content types (literal vs formula) and the clearing behavior, but it doesn't explain 'sheetIdx' beyond the schema's own comment. With partial coverage, the description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes one or more cells in a single atomic transaction, with specific addressing and content types. It distinguishes itself from the sibling 'set_block_cells' by emphasizing plain, non-block cells, and notes that block cells should use the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'For cells that belong to a block, prefer edit set_block_cells' and 'use this for plain, non-block cells,' providing clear when-to-use and when-not-to-use guidance with an alternative tool named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| block | Yes | ||
| field | Yes | ||
| validation | No | Boolean formula, e.g. "#PLACEHOLDER>=0". Pass null to clear; omit to leave existing untouched. | |
| editability | No | Boolean formula, e.g. "=#FIELD(\"status\")<>\"locked\"". Pass null to clear; omit to leave existing untouched. | |
| value_formula | No | Formula template, e.g. "=#FIELD(\"qty\")*#FIELD(\"price\")", or "=#FIELD(\"amt\")/#FIELD(\"amt\",\"TOTAL\")" to divide by a named row of the same block. Pass null to clear; omit to leave existing untouched. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly explains the engine behavior after the call for each rule kind (re-materialization, shadow installation, permission gate). It also discloses rejection criteria for self-referencing rules and coordinates landing on the block, and notes that leading '=' is optional—all beyond the annotations, which only provide readOnlyHint and destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense with essential information. It is front-loaded with the core purpose and optionality, then logically progresses to placeholder syntax, cross-row references, constraints, and engine behavior. Every sentence contributes value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for the tool's complexity: it covers what the tool does, how to use each parameter, what happens after the call, and what errors are rejected. It even addresses edge cases like row reordering and template coordinates. No output schema exists, but the description sufficiently indicates the effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 60%, the description adds substantial meaning to the parameters. It gives concrete examples for value_formula (e.g., multiplication, division by a named row), explains the #FIELD, #KEY, #PLACEHOLDER placeholders, and clarifies that passing null clears a rule while omitting leaves it unchanged—details not fully covered in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Attach declarative rules to a field," a specific verb+resource that clearly states the tool's function. It distinguishes three rule kinds (value_formula, validation, editability) and explains how they relate, making it distinct from sibling tools like set_cells or eval_formula.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool, how to leave rules untouched vs. clear them, and provides detailed guidance on placeholders, including when to use the two-argument #FIELD for cross-row references and why BLOCKREF is forbidden. It also notes that running totals have no rule form and directs users to write those as ordinary cells, giving clear exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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".
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | The cell to trace. Either (block, row_key, field) or (row, col). | |
| direction | No | both |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/destructive annotations, the description discloses critical behavior: it uses the engine's dependency graph, returns semantic names for block cells, and tracks dependencies per field rather than per row, causing over-approximation. It explicitly explains the 'scope' field and approximate flag, ensuring the agent understands the interpretive caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: starts with purpose, then usage, then behavior, then granularity caveats. Every sentence adds value and is directly relevant to correct use. Despite its length, it is not redundant; it front-loads the essential purpose and usage, followed by necessary technical detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (dependency tracing, block granularity, approximation), the description covers all key aspects: the two directions, naming, the engine's view through references, and the interpretation of field-wide results. It lacks an output schema, but the description suffices to understand what results will look like and how to use them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the schema: it explains the two naming conventions (semantic vs coordinate) for the target parameter, clarifies the default for direction ('Both by default'), and details how results are named. This compensates for the schema's partial coverage and adds practical guidance for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Follow a cell's dependencies, in either direction, using the engine's own dependency graph.' It specifies both directions (precedents/dependents) and gives concrete use cases, distinguishing it from sibling tools like eval_formula by mentioning it sees through BLOCKREF and ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: use precedents for auditing a number and dependents before changing something. It also contrasts with formula-string reading and explains when to rely on the result granularity, including how to interpret approximate results. This gives clear when-to-use and what-to-expect context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1chart_deletechart_from_blockchart_insertchart_listchart_updateconvert_to_block2 fields changedInput schema / properties / header_row / descriptionPrevious value: -"Row holding the column titles; field names are read from it. Usually one row above `position`."New value: +"Row holding the column titles; field names are read from it. Omit it and the row directly above `position` is used when it looks like a header — all text, over data that is not."Input schema / properties / key_fieldAdded value: +{
+ "description": "Which field identifies a row. Omit and the first column whose values are all present and all different is used.",
+ "type": "string"
+}create_block1 field changedInput schema / properties / descriptionAdded value: +{
+ "description": "What this table is for, in a sentence or two: what a row represents, what the fields mean where the names are not obvious, and anything a later reader must not do to it (e.g. a field the craft maintains). Saved with the block and returned by describe_block, so write it for whoever opens the file next rather than for this conversation.",
+ "type": "string"
+}set_block_descriptionv0.1.0add_block_rowsconvert_to_blockcreate_blockcreate_sheetdelete_block_rowsdescribe_blockeval_formulaexport_xlsxget_cellsgoal_seeklist_blockslist_violationsmove_block_rowopen_workbookpreview_changessave_workbookset_block_cellsset_cellsset_field_ruletraceScored across 26 tools
Each tool has a clearly distinct purpose: block operations, sheet operations, workbook operations, analysis tools, chart tools, and metadata. Even similar-sounding tools like set_cells vs set_block_cells are explicitly differentiated by whether they address blocks or raw cells, and chart_from_block vs chart_insert are distinguished by block-field vs range-based references. No two tools overlap in function.
Tool names follow a consistent verb_noun pattern with clear prefixes: block_* for block operations, chart_* for charts, and descriptive verbs for others (create_sheet, get_cells, open_workbook). All names use snake_case with verbs first, making them predictable and easy to parse. The only slight deviation is eval_formula, but it still fits the verb_noun pattern.
26 tools is slightly above the 16-25 range typically considered heavy, but the domain is a full spreadsheet application covering workbook lifecycle, block management, cell operations, formula evaluation, dependency analysis, goal seeking, validation, preview, charts, and import/export. Each tool earns its place given the breadth of functionality, so the count is justified despite being on the higher end.
The surface covers the full lifecycle of blocks (create, convert, add/delete/move rows, set cells, describe, set description), sheets (create, get/set cells), charts (insert/list/update/delete), workbook open/save/export, and advanced analysis (trace, goal seek, preview, validation). Minor gaps exist: there is no delete_sheet or delete_block tool, and block renaming is not directly supported, but these can be worked around by clearing content or recreating. Overall, the core workflows are well-covered.
Structured financial modeling for AI agents: build, version, audit models, export to Excel.
A structured financial modeling layer for AI agents. Build, version, and audit financial models without drift, then export to Excel, from Claude or any MCP client. Learn more: https://layerz.cc/for-agents
Connect AI assistants to Google Sheets through controlled tools for reading and updating rows.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
