Tools Overview

Sheetbase exposes 21 tools across five categories. Every tool name, description, and parameter in this documentation is sourced from the registered Zod tool schemas.

Tool surface

Tool	Category	Description
`list_spreadsheets`	Read	List all spreadsheets in Drive
`list_sheets`	Read	List tabs in a spreadsheet
`inspect_spreadsheet`	Read	Read-only spreadsheet recon: tab architecture, header/formula signals, type guesses, and risks
`read_range`	Read	Read a range — returns values + `_schema`
`search_rows`	Read	Fast server-side exact match search within a column
`write_range`	Write	Write a 2D array to a specific range
`append_rows`	Write	Append rows to the bottom of an existing table
`clear_range`	Write	Clear values in a range (keeps formatting)
`format_cells`	Write	Apply visual formatting using zero-based grid indexes
`analyze_range`	SQL	Execute Postgres SQL on a range — read-only
`transform_range`	SQL	Read → SQL transform → write back in-place
`create_spreadsheet`	Manage	Create a new blank spreadsheet
`manage_sheets`	Manage	Add, rename, or delete tabs via the REST API
`insert_column`	Manage	Insert a blank column before/after a safe ColumnRef target
`move_column`	Manage	Move a column before another column with formula/protection guards
`delete_column`	Manage	Permanently delete a column with confirmation and formula/protection guards
`delete_rows`	Manage	Permanently delete rows with semantic targeting and preview confirmation
`copy_sheet`	Manage	Copy a tab to another spreadsheet
`batch_update_sheet`	Manage	Structural updates: charts, merges, formatting
`restore_snapshot`	Manage	List and restore pre-write snapshots
`manage_drive`	Drive	Search Drive files, convert to Spreadsheets

All write tools (write_range, append_rows, transform_range) block by default if the target range contains formulas, overlaps a strict Protected Range, or intersects structured note guards such as [WARN], [FORMULA], or [LOCK]. Agents must pass the specific override (allowFormulaOverwrite or allowNoteGuardOverride) only after confirming the write is intentional.

2. AX over raw data transfer

analyze_range and transform_range exist specifically to keep raw tabular data out of the agent context window. An agent should never read_range on a large dataset just to compute a sum — that's what analyze_range is for.

3. Schema always co-delivered

read_range returns _schema alongside values in every response. analyze_range returns _schema alongside query results. Agents have structural sheet information without a separate tool call.

4. Recon before mutation

Use inspect_spreadsheet before broad transformations or destructive edits on an unfamiliar workbook. It returns a bounded, read-only architecture map so agents can identify likely transaction, reference, dashboard, calculation, and config tabs before choosing target ranges.

5. Destructive row deletes require preview

Use delete_rows for row deletion. It resolves 1-based rows, A1 ranges, or exact column matches, then returns a preview token before any delete occurs. Confirmation rechecks the row set and row-content fingerprint before calling the Sheets API.

6. Undo is available for value writes

Every write_range and transform_range call saves a before_values snapshot to write_history (≤ 1,000 rows). restore_snapshot can list and apply these snapshots. Row deletes store audit-only history and cannot be restored automatically.

7. Structural edits use focused tools first

Use insert_column, move_column, and delete_column for common column structure changes. They resolve human-friendly ColumnRefs, block ambiguous headers, and preflight formula/protected-range risks before calling the Sheets API.

8. 41% schema token savings (v1.1.0)

The Zod tool schemas were aggressively trimmed in v1.1.0 — removing redundant z.describe() attributes on self-evident fields. Total schema context load dropped from ~760 tokens to ~450 tokens per tool call. This directly increases agent reasoning budget per invocation.

MCP tool call anatomy

Every tool response uses the standard MCP content envelope:

{
  "content": [{
    "type": "text",
    "text": "{ ... JSON result ... }"
  }]
}

Errors add "isError": true and may include "needsAuth": true for expired OAuth sessions. See the Error Reference for the full error catalogue.

AX tool selection guide

Situation	Right tool	Wrong tool
Need to see what spreadsheets exist	`list_spreadsheets`	—
Need tab names + numeric IDs	`list_sheets`	—
Need to understand an unfamiliar workbook before edits	`inspect_spreadsheet`	ad hoc full-sheet reads
Preview sheet structure + small data	`read_range`	—
Aggregate 500+ rows	`analyze_range`	`read_range`
Reformat/enrich data in-place	`transform_range`	`read_range` → LLM → `write_range`
Add rows without overwriting	`append_rows`	`write_range`
Undo a write	`restore_snapshot`	Rewriting manually
Find a file in Drive	`manage_drive` search	`list_spreadsheets` (won't find CSVs)
Convert uploaded CSV to Sheets	`manage_drive` convert	—
Insert/move/delete columns safely	`insert_column` / `move_column` / `delete_column`	raw `batch_update_sheet` JSON
Delete rows safely	`delete_rows`	raw `batch_update_sheet` row indexes
Apply chart/merge/validation	`batch_update_sheet`	—