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.

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.