Tools Overview

sheets-mcp exposes 14 tools across five categories. Every tool name, description, and parameter in this documentation is sourced directly from the Zod schemas in route.ts.

Tool surface

Tool	Category	Description
`list_spreadsheets`	Read	List all spreadsheets in Drive
`list_sheets`	Read	List tabs in a spreadsheet
`read_range`	Read	Read a range — returns values + `_schema`
`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
`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 or overlaps a strict Protected Range. Agents must pass allowFormulaOverwrite: true to explicitly override. This is intentional — it prevents agents from silently destroying formulas.

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. Undo is always available

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.

5. 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`	—
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	—
Apply chart/merge/validation	`batch_update_sheet`	—