Google Sheets

Search sheets

Search the user's Google Sheets by name / parent / modifiedTime. Always scoped to spreadsheets — non-Sheets files are filtered out. Examples for `query`: "name contains 'Finances'", "'<folderId>' in parents and trashed = false", "modifiedTime > '2026-01-01T00:00:00Z'". Use before any mutating tool to resolve a sheet by name to its id.

List recent sheets

List the user's most recently modified Google Sheets, newest first.

Get sheet metadata

Fetch full metadata for a single Sheet by id: name, parents, owners, createdTime, modifiedTime, webViewLink. Always call this before a destructive mutation to confirm the right sheet.

Get sheet permissions

List who has access to a Sheet and at what role (owner, writer, commenter, reader). Returns one entry per principal (user, group, domain, anyone).

List revisions

List revisions of a Sheet. Each entry has id, modifiedTime, lastModifyingUser, and size. Use to audit who changed what when.

List sheet comments

Read a page of Sheets Drive comment threads, including replies and resolved state. Continue with nextPageToken until absent for a complete review.

Create sheet comment

Create a file-level review comment as the connected Google user. Not a native cell-anchored comment; include the tab name and A1 range in the text when relevant.

Reply sheet comment

Reply to an existing Sheets Drive comment as the connected Google user.

Set sheet comment status

Resolve or reopen a Sheets comment after user confirmation. confirm must equal resolve:comment_id or reopen:comment_id.

Read sheet range

Read a range from a Sheet by A1 notation. Open-ended ranges work (e.g. 'Stocks!A2:A' for all rows in column A starting at row 2). Returns a 2-D `values` array. Always read the label column before writing — the canonical pattern is read column A, align to an external source, then write the target column.

Update sheet range

Set cell values in an A1 range. Pass `values` as a 2-D array sized to match the range. Open-ended ranges are allowed (e.g. 'Stocks!D2:D'). Canonical pattern when syncing from another agent: read column A first to get the row labels, align an external source against them, then write only the target column. Never blank a cell when the external source has no match — pass the existing value through, or skip that row.

Append sheet rows

Append rows to a Sheets tab. Sheets scans the range for the last non-empty row and writes after it. Pass `values` as a 2-D array.

Export sheet

Export a Sheet to a downloadable format. Common targets: 'application/pdf', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' (xlsx), 'text/csv'. Returns base64 bytes. Capped at 25 MB.

Create sheet

Create a new empty Google Sheet. Optional `parents=[<folderId>]` to place it in a folder; defaults to the user's root.

Rename sheet

Rename a Sheet without moving it.

Copy sheet

Duplicate a Sheet. Optional new name and destination parents. Useful for templating: copy a tracking-sheet template, then write this period's values into the copy.

Trash sheet

Move a Sheet to the Drive trash. Recoverable via untrash_sheet or the Drive UI for 30 days. Prefer this over delete_sheet.

Untrash sheet

Restore a trashed Sheet to its previous parent folder.

Delete sheet

Permanently delete an entire SPREADSHEET FILE, bypassing trash. DESTRUCTIVE and unrecoverable. This is almost never what the user means: 'delete a row' → delete_rows; 'delete a column' → delete_columns; 'delete a tab' → delete_tab. Only call this when the user explicitly says 'delete the spreadsheet' / 'delete the file' / 'permanently'. The `confirm` argument must exactly match the spreadsheet name — fetch it via get_sheet_metadata and read it back to the user before asking them to confirm.

Share sheet

Add a permission to a Sheet. Type is 'user' / 'group' / 'domain' / 'anyone'. Role is 'reader' / 'commenter' / 'writer' / 'owner'. Confirm with the user before sharing externally (outside their domain) or granting writer/owner.

Update permission

Change the role on an existing Sheet permission. Use to upgrade a commenter to a writer, or downgrade a writer to a reader. To remove access entirely, use remove_permission.

Remove permission

Revoke access for a single permission entry. DESTRUCTIVE: the principal loses access immediately. The `confirm` argument must exactly match the principal's email address (or displayName for non-user permissions) — fetch via get_sheet_permissions and read it back to the user before they confirm.

Format sheet range

Apply text and cell formatting to an A1 range: bold/italic, font family + size, font + background color, alignment, wrap, and number format. Pass only the keys you want to change. Common patterns: bold the header row, currency format on a totals column, light-grey background on alternating bands.

Set borders

Apply borders to an A1 range. `sides` lists which sides get the border ('all' is shorthand for top/bottom/left/right + inner lines). Pass style='NONE' to clear borders. inner_horizontal and inner_vertical only apply to multi-cell ranges.

Merge cells

Merge or unmerge a rectangular A1 range. merge_type='MERGE_ALL' (default) makes one cell; 'MERGE_COLUMNS' merges each column into one cell; 'MERGE_ROWS' merges each row. Set unmerge=true to unmerge any merges within the range.

Resize columns

Resize a contiguous block of columns by letter. Either set pixel_width to an explicit number, or pass auto_fit=true to size each column to its content. Exactly one of the two options must be provided.

Freeze panes

Freeze the top N rows and/or first M columns on a tab so they stay visible while scrolling. Pass 0 for either to leave that axis unfrozen. Calling with both at 0 clears any existing freezes.

List tabs

List the tabs within a spreadsheet. Returns each tab's title, numeric sheetId, index (left-to-right order), and grid size. Use before mutating a specific tab to confirm its title and id.

Add tab

Add a new tab (a sheet within an existing spreadsheet). Use this when the user wants a 'new sheet' inside a spreadsheet they're already working in. For a brand-new file, use create_sheet instead. Returns the new tab's title and sheetId.

Rename tab

Rename a tab within a spreadsheet. To rename the spreadsheet (file) itself, use rename_sheet.

Duplicate tab

Duplicate a tab within the same spreadsheet, preserving values and formatting. Useful for templating ('copy last month's tab for this month').

Delete tab

Delete a single tab from a spreadsheet. DESTRUCTIVE: the tab and all its values are gone (recoverable only via the spreadsheet's revision history). The `confirm` argument must exactly match the tab's title — read it back to the user before they confirm. To delete rows/columns instead use delete_rows / delete_columns; to delete the whole spreadsheet file use delete_sheet.

Delete rows

Delete rows from a tab — the rows are removed entirely and rows below shift up. Use this (not update_sheet_range with blanks) when the user wants 'remove row 5' or 'delete the bottom 3 blank rows'. DESTRUCTIVE on non-empty rows; confirm first if the range has values. Row numbers are 1-based and inclusive — start_row=2, end_row=4 deletes rows 2, 3, 4.

Delete columns

Delete columns from a tab — columns to the right shift left. DESTRUCTIVE on non-empty columns; confirm first. Letters are inclusive — start_column='B', end_column='D' deletes B, C, D.