Connector for interacting with Google Sheets via the REST API. Supports reading spreadsheet data, applying raw spreadsheet batch updates, creating spreadsheets, and fetching the current user's profile.
add_sheet_to_spreadsheetAdd a new sheet to an existing spreadsheet.
sheet_namestringExact sheet tab title (e.g. Sheet1 or Q1 Plan). Do not add A1 quotes, !, or coordinates.
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
append_rangeAppend values to the end of a logical table within a spreadsheet.
Preferred tool for adding new rows at the bottom of existing data.
rangestringOptional A1 range used to find the logical table to append to, e.g. A1:D1 or B:E. Do not include the sheet name here and avoid partial bounds like A1:D. Use append_range whenever the intent is 'add row(s) at the bottom' so Google Sheets picks the next row automatically (instead of manually targeting A{n+1}:...). Pass null to append using the whole sheet.
sheet_namestringSheet tab name only (no ! or coordinates). For A1 notation compatibility, quote names with spaces/punctuation (e.g. 'Q1 Plan'). If the name contains a single quote, escape it as two single quotes inside the quoted name (e.g. 'O''Reilly').
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
valuesarrayRows to append. Each inner list is one row. Keep column count consistent with your table schema.
batch_updateApply raw Google Sheets batchUpdate requests to a spreadsheet.
If editing a spreadsheet created earlier in the turn, wait for the create or duplicate action to return successfully before calling this action. Use only the spreadsheet ID or URL returned by that earlier action.
requestsarrayRaw Google Sheets API batchUpdate requests, in execution order. Each item should use the Sheets REST request shape directly, for example {'addSheet': {...}} or {'updateCells': {...}}. Use Google field names and casing exactly. Send each request as a structured object, not as a JSON string or other stringified input.
include_spreadsheet_in_responsebooleanWhen true, include the updated spreadsheet resource in the response.
Falseresponse_include_grid_databooleanWhen true, include grid data in updatedSpreadsheet. Only meaningful when include_spreadsheet_in_response is true.
Falseresponse_rangesarrayOptional A1 ranges to include in updatedSpreadsheet when include_spreadsheet_in_response is true.
nullspreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullclear_rangeClear values from a range of cells within a spreadsheet.
sheet_namestringSheet tab name only (no ! or coordinates). For A1 notation compatibility, quote names with spaces/punctuation (e.g. 'Q1 Plan'). If the name contains a single quote, escape it as two single quotes inside the quoted name (e.g. 'O''Reilly').
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
rangestringThe range of cells to clear (A1 or R1C1 notation). Use null to clear the entire sheet.
nullcreate_chartCreate an embedded chart on a new sheet from the specified range.
chart_titlestringTitle for the chart
rangestringPrimary chart source range in bounded A1 notation with explicit start/end cells, e.g. A1:B20. Do not include sheet name. Use exactly two columns here: first column for labels, second column for the first numeric series. Add any extra series through series_ranges/secondary_series_ranges.
sheet_namestringExact sheet tab name containing the chart data (for this tool, pass the literal tab name without A1 quoting).
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
anchor_cellstringOptional anchor cell like F1 (single cell only, no sheet prefix). Use null to create chart on a new sheet.
nullchart_typestringChart type: COLUMN, LINE, BAR, SCATTER, AREA, COMBO, STEPPED_AREA. If using stacked_type, prefer COLUMN/AREA/BAR; LINE often rejects stacked_type. BAR can be stricter about series axis assignments in Google Sheets.
COLUMNheader_countintegerNumber of header rows at the top of the range to use for labels (e.g., 1 to use row 1).
nulllegend_positionstringLegend position: BOTTOM_LEGEND, TOP_LEGEND, LEFT_LEGEND, RIGHT_LEGEND, NO_LEGEND
BOTTOM_LEGENDsecondary_series_rangesarrayOptional ranges for series on the right axis. Each entry must be a single-row or single-column bounded A1 range (e.g. D1:D20), with no sheet prefix.
nullseries_rangesarrayOptional additional series ranges on the left axis. Each entry must be a single-row or single-column bounded A1 range (e.g. C1:C20), with no sheet prefix.
nullstacked_typestringStacking option: STACKED, PERCENT_STACKED, or NOT_STACKED. Set only when supported by chart_type.
nulltitle_font_colorstringOptional hex color or named color for the chart title text (e.g. '#1A2B3C' or 'black').
nulltitle_font_familystringOptional font family for the chart title, e.g. 'Arial'.
nulltitle_font_sizeintegerOptional font size (points) for the chart title.
nullx_axis_titlestringCustom title for X-axis
X-Axisy_axis_titlestringCustom title for Y-axis
Y-Axiscreate_spreadsheetCreate a new spreadsheet with an initial sheet.
This creation flow is eventually consistent. Do not mention or synthesize a Google Sheets URL until this action returns, and then use only the spreadsheet URL returned in the response.
titlestringThe title of the spreadsheet document.
sheet_namestringThe name of the first sheet in the new spreadsheet. Use null for the default name 'Sheet1'.
nullduplicate_sheetDuplicate an existing sheet within a spreadsheet.
source_sheet_namestringExact sheet tab title (e.g. Sheet1 or Q1 Plan). Do not add A1 quotes, !, or coordinates.
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
insert_indexintegerOptional index where the new sheet should be inserted (0-based). Use null to append at end.
nullnew_sheet_namestringOptional name for the duplicate sheet. Must be unique in the spreadsheet and 100 characters or fewer. Use null to let Google assign a unique name.
nullduplicate_sheet_in_new_fileDuplicate an existing sheet into a newly created spreadsheet file.
This creation flow is eventually consistent. Do not mention or synthesize a Google Sheets URL until this action returns, and then use only the spreadsheet URL returned in the response.
new_file_namestringsource_sheet_namestringnew_sheet_namestringnullspreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullexportExport a Google Sheet to the requested MIME type.
mime_typestringExport MIME type understood by Google Drive files.export, for example application/pdf, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, or text/csv.
application/pdfspreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullget_cellsRead cell data from one or more bounded ranges using the Google Sheets CellData shape.
Prefer this action over get_range for most reads. Use get_range only when all you need is the sheet's plain values; use get_cells for formatting, formulas, validation, notes, hyperlinks, and other cell metadata.
rangesarrayOne or more A1 ranges including the sheet name, e.g. ['Sheet1!A1:C20']. Keep each range within existing sheet bounds.
cell_fieldsstringRaw Google Sheets CellData field mask fragment. Examples: 'formattedValue,effectiveValue' or 'formattedValue,userEnteredValue,effectiveFormat(textFormat,numberFormat)'. Default: 'userEnteredValue,userEnteredFormat'. Prefer this action over `get_range` unless you only need the plain cell values; use this action for formatting, formulas, validation, notes, hyperlinks, and other cell metadata.
nullspreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullget_profileReturn the connected Google account profile.
get_rangeRead only the plain values from a range of cells within a spreadsheet.
Use get_cells instead when you need cell values together with formatting, formulas, validation, notes, hyperlinks, or other CellData.
rangestringCell range only (A1 or R1C1), e.g. A1:B10, A:Z, or 1:200. Do not include the sheet name here (pass it only in sheet_name), and do not pass duplicated prefixes like Sheet1!Sheet1!A1:B10. Keep the range within existing sheet bounds. Use this action only when you need the plain values of a range; use `get_cells` when you need cell values together with formatting, formulas, validation, notes, hyperlinks, or other cell metadata.
sheet_namestringSheet tab name only (no ! or coordinates). For A1 notation compatibility, quote names with spaces/punctuation (e.g. 'Q1 Plan'). If the name contains a single quote, escape it as two single quotes inside the quoted name (e.g. 'O''Reilly').
spreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullvalue_render_optionThe option to render the values, e.g. 'FORMATTED_VALUE', 'UNFORMATTED_VALUE' or 'FORMULA'. Use null for default.
nullget_spreadsheet_commentsRead user comments and replies on a Google Sheets spreadsheet for additional review context.
include_deletedbooleanWhen true, include deleted comments and deleted replies in the result.
Falsepage_sizeintegerMaximum comment threads to return on this page. Use the response nextPageToken to continue.
100page_tokenstringOpaque nextPageToken from a previous get_spreadsheet_comments response.
nullspreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullget_spreadsheet_metadataGet metadata about a spreadsheet.
charts_onlybooleanWhen true, return only sheet properties and chart IDs/titles.
Falseinclude_conditional_format_rulesbooleanWhen true, include per-sheet conditional formatting rules in the response.
Falsespreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullinsert_rangeInsert one or more rows at the specified location and populate them with values.
sheet_namestringExact sheet tab title (e.g. Sheet1 or Q1 Plan). Do not add A1 quotes, !, or coordinates.
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
start_row_indexinteger0-based index where to insert rows (0 = before first row, 1 = before second row, etc.)
valuesarrayValues to populate the inserted rows. The number of rows will be inferred from this.
search_rowsSearch for rows containing a query string and return matching rows as a Markdown table.
Usage guidance:
column positions; it is often a header row.
and is preferable to retrieving the entire range, which can exhaust the context window.
relative to the provided range (the header row is left blank).
Implementation notes: this tool fetches the full selected range, scans each row client-side, and returns all matching rows with the requested columns.
querystringString to search for in any cell within each row.
rangestringCell range to search (A1 or R1C1), e.g. A1:Z200. Do not include the sheet name here (passing Sheet1!A1:Z200 will fail because sheet_name is prepended automatically).
sheet_namestringSheet tab name only (no ! or coordinates). For A1 notation compatibility, quote names with spaces/punctuation (e.g. 'Q1 Plan'). If the name contains a single quote, escape it as two single quotes inside the quoted name (e.g. 'O''Reilly').
column_numbersarray1-based column numbers to return. Use null to return all columns (up to max_columns).
nullinclude_header_rowbooleanWhen true, always include the header row as the first data row in the output.
Truemax_columnsintegerMaximum number of columns to return when column_numbers is null. Default is 100.
100max_rowsintegerMaximum number of rows to return from the selected range. Default is 500.
500spreadsheet_idstringRaw Google Sheets spreadsheet ID only (for example `1abcDEF...`). Use this when you already have the ID from a prior search result. Do not pass a full URL here.
nullspreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID. If you only know the spreadsheet title or title keywords, call `search_spreadsheets` first instead of asking the user for a URL.
nullsearch_spreadsheetsSearch Google Drive for Google Sheets spreadsheets by title before reading or editing.
querystringKeyword query for finding a Google Sheets spreadsheet in Drive. Use the spreadsheet title or short title keywords, not a long natural-language instruction.
require_viewed_by_userbooleanWhen true, keep only spreadsheets viewed by the authenticated user.
FalsetopnintegerMaximum spreadsheets to return. Parameter name is `topn`.
10write_rangeWrite values to an exact range of cells within a spreadsheet.
Use this when you have a specific destination range (for example A2:D2 or A2:D200). This does not auto-append after the last populated row. If you need to add rows, use append_range (bottom) or insert_range (specific index).
rangestringTarget cell range only (A1 or R1C1), e.g. A1:B10. Do not include the sheet name here. Use write_range only when you know the exact destination cells already exist and you intend to write/overwrite those cells. write_range does not grow sheet dimensions, so guessed next-row writes (like A3:D3) can fail with grid limit errors. For adding a new row at the bottom of existing data, use append_range instead.
sheet_namestringSheet tab name only (no ! or coordinates). For A1 notation compatibility, quote names with spaces/punctuation (e.g. 'Q1 Plan'). If the name contains a single quote, escape it as two single quotes inside the quoted name (e.g. 'O''Reilly').
spreadsheet_urlstringGoogle Sheets spreadsheet URL in the format https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/... or a raw spreadsheet ID.
valuesarray2D row-major matrix of values to write. Matrix height/width must not exceed the specified range bounds (e.g. two rows and three columns requires a range that can hold 2x3 cells).