Google Sheets
Service domainSPREADSHEETS
Arcade Optimized
Arcade.dev LLM tools for Google Sheets.
12tools
10require secrets
Google Sheets Toolkit
Arcade toolkit for Google Sheets that enables LLMs to read, write, inspect, search, and annotate spreadsheets via the Google Sheets and Drive APIs, including access-control pre-flight checks and inline file picking.
Capabilities
- Access & discovery: Check batched spreadsheet accessibility before reads, generate Google Drive picker URLs for granting per-file access, search Drive for spreadsheets by title/content, and retrieve connected-account identity.
- Read & inspect: Inspect workbook structure (tabs, merges, charts, protected ranges, conditional formats, table regions) or read arbitrary cell ranges with optional per-cell annotations, markdown/CSV/TSV export, and column filtering.
- Write & edit: Create new spreadsheets or batch-edit existing ones using the full Sheets
requests[]API (updateCells, addSheet, sortRange, autoResizeDimensions, conditional formatting, and more). - Data quality scanning: Deterministically flag bad/anomalous cells by rule and severity (no LLM inference), with grouped or per-cell output ready for annotation workflows; supports single-tab or whole-workbook scans with partial-result handling on rate limits.
- Comments & collaboration: List, create, edit, resolve, reopen, reply to, and delete comment threads; retrieve edit history (contributors, timestamps) from Drive revisions.
OAuth
This toolkit uses OAuth 2.0 via Google. See the Arcade Google auth provider docs for setup details.
Secrets
ENABLE_GOOGLE_DRIVE_INLINE_PICKER_URL— Controls whether the toolkit embeds a single Google Drive picker URL directly inCheckSpreadsheetAccessresponses (thegrantblock) rather than requiring a separate call toGenerateGoogleFilePickerUrl. Set this to enable the inline picker feature. This is an Arcade-side configuration secret, not a Google credential — no Google dashboard action is required. Create and manage it in the Arcade secrets dashboard.
For general guidance on defining secrets in Arcade tools, see the Arcade secrets docs.
Available tools(12)
12 of 12 tools
Operations
Behavior
| Tool name | Description | Secrets | |
|---|---|---|---|
Check whether this app can already read each of several spreadsheets, in one
batched pre-flight call, before attempting to read them.
Use this when the user references multiple spreadsheets, to learn which are readable up
front instead of hitting a separate access error for each one. Where this app reaches
spreadsheets one grant at a time, the ungranted ones can then be granted together in a
single picker step. Each input may be a bare file id or a full Google Sheets/Drive URL.
Returns ``spreadsheets`` (a per-id list with ``accessible``, the ``title`` and
``mime_type`` when the file was read, and a ``reason`` when not usable),
``all_accessible`` (true only when every id is an already-accessible spreadsheet),
``connected_account_email`` (the connected Google account, empty when unknown), and a
``grant`` block. ``grant`` lists the ungranted ids (``ungranted_ids``) plus, when the
inline picker is enabled, a single picker URL covering them all. Where this app already
reaches every spreadsheet the account can open there is no per-file grant to make, so
``ungranted_ids`` stays empty and only ``access_hint`` comes back.
A ``reason`` of ``not_accessible_or_not_found`` is a spreadsheet this app cannot read:
one not granted to it yet, one that does not exist, or one the connected account itself
cannot open — indistinguishable here. For those ids specifically, an empty
``ungranted_ids`` means no grant step exists, so treat them as not found rather than
asking the user to grant them. Read that only against ``not_accessible_or_not_found``:
``ungranted_ids`` is also empty when nothing needs granting at all, and for every reason
below, none of which a grant would resolve.
``not_a_spreadsheet`` is an accessible file of another type (a Doc, PDF, image, or
Excel/CSV file); granting cannot change a type, so for an Excel/CSV file ask the user
to open it in Google Sheets and use File, Save as Google Sheets, then share the
converted file. ``invalid_reference`` is an input that is not a Drive id or link at all;
ask the user to re-check it. ``rate_limited`` means Google throttled the check for that
id, so its reachability is still unknown: wait briefly and call again for those ids, and
do not ask the user to grant them. ``error`` is any other failure to complete the check
(a timeout or a Google server error) and is likewise unknown rather than denied.
``type_unknown`` is a readable file whose type Google did not report - unlike
``not_a_spreadsheet`` it is not a statement that the file is something else, so retry it
rather than telling the user to convert it.
``dropped_selector`` is non-empty when the input was a link naming a specific tab or
range (``gid=847362514``) that the file id does not carry. The file is still reported
normally, but the other tools reject such a link rather than silently applying to the
workbook's first tab - so pass the ``id`` from this result plus that tab named
explicitly, and do not forward the original URL. | 1 | ||
Create a comment on a spreadsheet, edit a comment's body, or resolve/reopen it.
Comments are created at the file level: the Drive API cannot anchor a NEW Sheets comment to a
specific cell or range. Cell/range-anchored comments made in the Sheets UI are still readable
via list_spreadsheet_comments (which returns their anchor). Editing a comment's body is
allowed only for the comment's author. | 1 | ||
Create a new spreadsheet or batch-edit an existing one.
Omit `spreadsheet_id` to create; provide it to edit. All writes flow through
`requests[]` — typed operations like updateCells, addSheet, sortRange,
addConditionalFormatRule, autoResizeDimensions, and more.
For updateCells use ExtendedValue with an explicit type field (stringValue,
numberValue, boolValue, formulaValue).
By default, build clean, professional-looking tables with restrained, consistent
formatting and plain-text tab names/headers (no emojis); only use emojis or
decorative styling when the user explicitly asks for it. | 1 | ||
Delete a comment from a spreadsheet.
Only the comment's author can delete it (enforced by Google Drive); deleting marks the
whole thread (the comment and its replies) as deleted. | 1 | ||
Generate a URL where the user can grant this app access to spreadsheets.
Check `url` first. An empty `url` means this app already reaches every spreadsheet the
connected account can open, so there is no per-file grant to request: this tool cannot
change any outcome, and a spreadsheet that could not be read is one the account itself
cannot open. Do not retry it.
Otherwise the URL opens Google's first-party Drive picker, filtered to Google Sheets,
where the user browses and selects which spreadsheets to share with this application —
it is not a sign-in or credential prompt. Use this when a prior tool reported that a
file was not found or access was denied, and the user expects the file to exist. After
the user completes the picker flow, retry the prior operation. | |||
Report who edited a spreadsheet and when, from Google Drive revisions.
Reports the "who" and "when" only — not which cells changed, and it can't revert.
'summary' (default) answers "who last edited this and when" (read from the file's head,
so always accurate), plus per-window aggregates (revisions read, contributors, first
edit) and a preview of recent edits — computed over a bounded window of history per call.
These aggregates describe the whole history only when `is_incomplete` is false; it is
true when the scan was resumed from a token and/or more history remains. To answer
"when was this first edited?" or "who contributed?" reliably, call from the beginning
(no `pagination_token`) and check `is_incomplete` is false. `pagination_token` is
returned when more pages remain so you can resume.
'list' returns one page of individual revisions, oldest first. Drive can't sort
newest-first, so the most recent individual revisions are on the final page. | 1 | ||
Inspect a Google Sheets spreadsheet's structure or read a range of cells.
Use the default 'structure' mode to understand a workbook cheaply before reading.
Switch to 'read' mode to pull a range as a grid of rows, optionally with
per-cell annotations and a rendered markdown/csv/tsv export.
In 'read' mode the response's per-tab 'sheets' block reports only tab identity and
the allocated grid; its scan-derived fields (used_range, populated_cell_count,
formula_cell_count, first_row, table_regions) are placeholders (0/empty) because read
mode does not scan the tab — they do NOT mean the tab is empty or that it has no
tables. The data you read is in the top-level 'range' and 'rows'. Call 'structure'
mode for those aggregates and for the workbook's charts, merges, protected ranges, and
conditional formats.
Workflow for a tab that holds multiple tables, or a table that does not start at A1:
call 'structure' first and use that tab's estimated 'table_regions' to choose the
a1_range to read or filter, so you target one table instead of a glued multi-table
range.
Always check the response's top-level 'warnings' list: read mode reports there when a
result was capped or trimmed (cell budget, the per-cell annotation cap, or an empty
filter scan) and tells you how to recover (page 'next_range', narrow 'a1_range',
'select_columns', or request fewer annotation kinds). | 1 | ||
List a spreadsheet's comment threads, or the full replies of a single comment.
In 'comments' mode each comment includes up to a few trimmed reply previews plus the total reply_count; use 'thread' mode for a comment's complete reply list. Without filters/ordering, pagination walks every comment. Client-side filters (has_replies, resolved) and order_by are applied only within a bounded scan of the first 500 comments, so on larger sheets drop them and page through everything with the native (unbounded) pagination. Each comment's Drive anchor is returned when it was cell/range-anchored in the Sheets UI; comments created via the API are file-level. Filtering, ordering, and offset pagination are best-effort: results can drift if comments are added or removed between paginated calls. | 1 | ||
Add a reply to an existing comment on a spreadsheet.
To resolve or reopen the comment instead, use comment_on_spreadsheet with a status. | 1 | ||
Deterministically flag 'weird'/bad cells in spreadsheet data.
No LLM judgement: the same input always returns the same flags. Each cell-level finding
carries a coord, a 0-based row_index/column_index (ready for a Sheets GridRange), the rule,
a severity (high -> red, medium/low -> yellow), and a note-ready reason — so the output
drops straight into an annotate/format recipe. In the default `mode='grouped'` these are
aggregated per rule+column within each table into `groups` (with A1 `coords`); use
`mode='list'` to get every flagged cell in `flags` with its 0-based indices.
Provide `spreadsheet_id` to scan a live sheet (scan one tab via sheet_id/sheet_title, or
every tab when both are omitted). Set `orientation='rows'` for transposed tables whose
fields run down a column instead of across a row. Findings come back as flags (cell-level,
high certainty) and alerts (table-level, lower certainty), grouped sheet -> table -> rule.
In all-sheets mode a tab that cannot be read is collected in `failed_sheets` (and echoed
as a `warnings` entry) while every other tab still returns; `failed_sheets` is empty for
a single-tab scan and whenever every tab reads cleanly.
CHECK `complete` BEFORE REPORTING. `total_flag_count` counts only the `sheets_scanned`
tabs out of `sheets_targeted`, so a partial scan that reports zero flags is not a
statement that the workbook is clean. When `complete` is false, say which tabs were
covered. Rate limiting is the usual cause: all-sheets mode spends one read per tab
against Google's per-minute quota, so a throttle part way through returns the tabs
already scanned with `complete: false` and every tab it never reached listed in
`unscanned_sheet_titles`. Wait about a minute, then scan those - one `sheet_title` per
call, or re-run the whole workbook. Every title in that list is still unchecked, so
stopping after the first one leaves the workbook half-scanned. A throttle before any tab
was scanned has nothing to return, so it fails as retryable instead. | 1 | ||
Searches for spreadsheets in the user's Google Drive based on the titles and content and
returns the title, ID, and URL for each matching spreadsheet.
Does not return the content/data of the sheets in the spreadsheets - only the metadata.
Excludes spreadsheets that are in the trash.
`pagination_token` is present only when more results remain; pass it back to continue.
An empty result set carries an `access_hint` explaining that this app only sees
spreadsheets it has been granted, along with a URL for granting more when available. | 1 | ||
Identify the Google account this app is connected through.
Use this to tell the user which account is in play, or to resolve "me" in a request
that names a person. Returns the connected account's display name, given and family
name, formatted name, primary email address, and profile picture URL, read from the
Google People API.
A field is an empty string when Google does not supply it. This reports identity only
and does not check whether that account can reach any particular spreadsheet — use
check_spreadsheet_access for that. |
Get Building
Last updated on