Google Sheets

GoogleSheets_CheckSpreadsheetAccess

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.

GoogleSheets_CommentOnSpreadsheet

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 can still be read by listing the spreadsheet's comments, which returns their anchor. Editing a comment's body is allowed only for the comment's author.

GoogleSheets_CreateOrEditSpreadsheet

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.

GoogleSheets_DeleteComment

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.

GoogleSheets_GenerateGoogleFilePickerUrl

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.

GoogleSheets_GetSpreadsheetEditHistory

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.

GoogleSheets_InspectSpreadsheet

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

GoogleSheets_ListSpreadsheetComments

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.

GoogleSheets_ReplyToComment

Add a reply to an existing comment on a spreadsheet. This only adds a reply. Resolving or reopening the comment is a status change on the comment itself.

GoogleSheets_ScanForDataIssues

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.

GoogleSheets_SearchSpreadsheets

Search for spreadsheets in the user's Google Drive based on the titles and content and return 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.

GoogleSheets_WhoAmI

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.