Read Tools

list_spreadsheets, list_sheets, read_range — inspect your Sheets without writing anything.

`list_spreadsheets`

Lists all Google Spreadsheets in the authenticated user's Drive.

No parameters required.

// Response — array of file objects
[
  {
    "id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "name": "Q2 2026 Revenue",
    "createdTime": "2026-03-01T09:00:00.000Z",
    "modifiedTime": "2026-05-12T14:23:00.000Z"
  }
]

Note

Uses driveClient.files.list with mimeType='application/vnd.google-apps.spreadsheet' and spaces: 'drive'. Returns files in default Drive sort order. Does not page — if you have hundreds of spreadsheets, use manage_drive search with a name query to narrow results.

`list_sheets`

Lists all tabs (worksheets) inside a spreadsheet, with their numeric sheetId and tab index.

Parameter	Type	Required	Description
`spreadsheetId`	`string`	✓	The spreadsheet to inspect

// Response — array of sheet tab objects
[
  { "sheetId": 0,         "title": "Sheet1",   "index": 0 },
  { "sheetId": 812345678, "title": "Revenue",  "index": 1 },
  { "sheetId": 923456789, "title": "Archive",  "index": 2 }
]

Tip:

Always call list_sheets before using format_cells, copy_sheet, manage_sheets (rename/delete), or batch_update_sheet — these tools require the numeric sheetId, not the tab name string.

`read_range`

Reads a 2D array of cell values from a range, along with the sheet's structural schema.

Parameter	Type	Required	Default	Description
`spreadsheetId`	`string`	✓	—	Target spreadsheet
`range`	`string`	✓	—	A1 notation, e.g. `Sheet1!A1:D10`
`renderOption`	`enum`	✗	`FORMATTED_VALUE`	How values are rendered (see below)

`renderOption` values

Value	Returns
`FORMATTED_VALUE`	What the user sees — `$1,200.00`, `Jan 2026`, `TRUE`
`UNFORMATTED_VALUE`	Raw underlying value — `1200`, `46023` (serial date), `true`
`FORMULA`	Cell formula strings — `=SUM(A1:A5)`, or the value if not a formula

Response shape

read_range always bundles the sheet schema with the values:

{
  "values": [
    ["Name", "Revenue", "Status"],
    ["Acme Corp", "$12,000", "Active"],
    ["Globex", "$8,500", "Inactive"]
  ],
  "_schema": {
    "layout": { "frozenRows": 1, "frozenColumns": 0 },
    "semantics": ["Has 3 conditional format rules"],
    "protectedRanges": [],
    "arrayFormulaColumns": ["C"],
    "warnings": ["⚠ Column C contains ARRAYFORMULA — do not write to C2:C"],
    "mergedTitleRows": [],
    "constraints": []
  }
}

AX: Read _schema before writing. The _schema is fetched in parallel with the range data (zero extra latency). Check arrayFormulaColumns and protectedRanges before calling any write tool on this range.

Truncation behaviour

If the response exceeds 1,000 rows or 2 MB, the result is truncated and a warning is appended:

⚠ read_range: Truncated to 1000 rows (original: 14823).
Use a narrower A1 range or analyze_range with SQL for large datasets.

When you see this warning, switch to analyze_range — do not retry read_range on the same large range.

Common A1 patterns

Sheet1!A1:D10       — rows 1–10, columns A–D
Sheet1!A:D          — entire columns A–D (all rows)
Sheet1!1:1          — entire row 1 (header row only)
'My Sheet'!A1:Z100  — sheet name with spaces (single-quoted)

Warning: Always qualify the range with the sheet name (Sheet1!A1). Without the sheet name prefix, the Sheets API defaults to the first tab, which may not be what you expect.

Read Tools

list_spreadsheets

list_sheets

read_range

renderOption values