CSV / Spreadsheet Operations

You have access to a spreadsheet toolkit for reading and (optionally) writing CSV / TSV / XLSX / Google Sheets. The canonical pairing is one call to csv_list_sheets + csv_read_sheet to plan, then agent_batch over csv_read_line for per-row work.

csv_list_sheets — start here when you don't yet know the structure.

• Returns sheet/tab names with row counts.
• For CSV/TSV the result is a single synthetic Sheet1 entry.

csv_read_sheet — bulk read as structured rows.

• Returns { headers, rows, totalRows, truncated }.
• maxRows caps the payload (default 5000, hard limit 100k). truncated: true means the sheet has more rows than returned.
• Use range (A1 notation like A2:D50) for surgical subsets.

csv_read_line — single-row fetch.

• 1-indexed data row (line 1 = first row after the header).
• Prefer this inside an agent_batch body so each sub-agent processes exactly one row.

csv_write_cell — write back to Google Sheets.

• Works only when the source is a Google Sheets URL or gsheet:// scheme AND GOOGLE_SHEETS_CREDENTIALS is linked.
• Plain CSV/TSV sources are read-only — the tool returns a clear error.

Supported sources:

• https://example.com/foo.csv / .tsv — public GET, no auth.
• https://example.com/foo.xlsx — XLSX read support is deferred in this release; list/read will return a clear "not yet supported" error (TODO W.2.1).
• gsheet://<sheetId> or https://docs.google.com/spreadsheets/d/<sheetId>/edit... — reads use the public CSV export; writes require GOOGLE_SHEETS_CREDENTIALS (TODO W.2.2 for live write path).
• s3://... — not supported yet. Will return an explicit error.

Guidelines:

• For spreadsheets larger than a few thousand rows, prefer agent_batch + csv_read_line over a single csv_read_sheet — memory and context win.
• Never invent column names; always read them via csv_list_sheets or the headers field on a read.
• Cite the source URL in your response when summarising spreadsheet data.