Read Tools

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.

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

renderOption values

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 search_rows for exact row lookup, analyze_range with SQL for aggregates/filtering, or a narrower A1 range for bounded samples.

When you see this warning, do not retry read_range on the same large range. Use search_rows for exact row lookup, analyze_range for aggregates/filtering, or a narrower A1 range for bounded samples.

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.

Spreadsheet Timezone

inspect_spreadsheet retrieves the spreadsheet's IANA timezone from properties.timeZone and includes it in the recon output. When date or timestamp columns are detected, the recon warns which timezone governs analysis and falls back to Etc/UTC with an explicit disclosure if the metadata is missing or invalid. Invalid or unrecognized IANA identifiers also fall back safely to Etc/UTC and are disclosed as invalid (not "missing") so the distinction is visible.

analyze_range fetches the spreadsheet's IANA timezone alongside the range data and includes it in the _schema output:

{
  "_schema": {
    "spreadsheetTimezone": "America/Los_Angeles",
    "spreadsheetTimezoneFallback": false,
    ...
  }
}

Use _schema.spreadsheetTimezone when grouping timestamps by calendar day or checking date-range membership — this is the authoritative timezone for that spreadsheet.

read_range returns cell values exactly as the Sheets API renders them (formatted strings, raw values, or formula strings). It does not apply timezone conversion — if you are interpreting date serial numbers or timestamps from UNFORMATTED_VALUE results, use the spreadsheet timezone from inspect_spreadsheet or analyze_range _schema to guide your analysis.

Date-only serials: Google Sheets stores date-only cells as integer serials (days since 1899-12-30). Serial 46023 = calendar date 2026-01-01. A date-only serial is a spreadsheet-local calendar value — it should not be converted to a Unix timestamp before comparing to date ranges, as that would shift the date by the UTC offset. Compare date strings directly using the spreadsheet timezone.