Built-in tool
Read Google Sheet
Read a connected Google Sheet by Drive title, URL/ID, tab, range, or matching rows.
1 creditNo API key neededEndpoint
Parameters
| Name | Type | Required | Note |
|---|---|---|---|
| actionstring · required | string | required | Google Sheets read action to perform. get-sheet-info: retrieve spreadsheet metadata — title, list of sheet tab names, and their row/column counts. read-range: read cells from a specific A1 notation range (e.g. "Sheet1!A1:D10"). Returns a 2D array of values. read-all: read every row from a named sheet and return an array of objects using the first row as column headers. search-rows: scan all rows in a sheet and return rows where a specific column header's value contains the search string. One of: |
| rangestring · optional | string | optional | A1 notation range for the read-range action (e.g. "Sheet1!A1:D10", "Sheet1!A:C", "A1:B5"). Include the sheet name prefix for clarity. Required when action is read-range. |
| accountIdstring · optional | string | optional | Optional connection ID or account name to use a specific Google Sheets account. If omitted, the first active Google Sheets integration in the workspace is used automatically. |
| sheetNamestring · optional | string | optional | Name of the sheet tab to read from (the tab label at the bottom of the spreadsheet). For read-all and search-rows, omission selects the spreadsheet's first real tab. Use get-sheet-info first when the user wants a particular tab but has not named it. |
| searchValuestring · optional | string | optional | Value to search for in the specified column for the search-rows action. Case-insensitive substring match — a row is returned if its cell value contains this string. Required when action is search-rows. |
| searchColumnstring · optional | string | optional | Column header name to search within for the search-rows action. Must exactly match a header in the first row of the sheet. Example: "Email", "Company Name", "Status". |
| spreadsheetIdstring · optional | string | optional | Google Sheets spreadsheet ID. Found in the spreadsheet URL: https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit. Example: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms". Provide this OR spreadsheetName. |
| spreadsheetNamestring · optional | string | optional | Exact Google Drive file title, for example "Sales Tracker". Use this when the user names their Google Sheet but does not provide a URL or spreadsheet ID. The tool resolves the title in the connected account and safely reports no match or duplicate-title ambiguity. Provide this OR spreadsheetId. |
Response schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"success",
"action"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Array of row objects keyed by header name (read-all, search-rows)."
},
"range": {
"type": "string",
"description": "The range that was read."
},
"title": {
"type": "string",
"description": "Spreadsheet title (get-sheet-info)."
},
"action": {
"type": "string"
},
"sheets": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"index",
"rowCount",
"columnCount"
],
"properties": {
"index": {
"type": "number"
},
"title": {
"type": "string"
},
"sheetId": {
"type": "number"
},
"rowCount": {
"type": "number"
},
"columnCount": {
"type": "number"
}
},
"additionalProperties": false
},
"description": "List of sheet tabs with dimensions (get-sheet-info)."
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {}
},
"description": "2D array of cell values (read-range)."
},
"headers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Column headers from the first row."
},
"message": {
"type": "string"
},
"success": {
"type": "boolean"
},
"rowCount": {
"type": "number",
"description": "Number of data rows returned (excludes the header row)."
},
"errorCode": {
"enum": [
"SPREADSHEET_INPUT_REQUIRED",
"SPREADSHEET_NOT_FOUND",
"SPREADSHEET_AMBIGUOUS",
"SPREADSHEET_LOOKUP_FAILED",
"GOOGLE_SHEETS_ACCOUNT_AMBIGUOUS"
],
"type": "string"
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"spreadsheetId",
"title",
"url"
],
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"spreadsheetId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"spreadsheetId": {
"type": "string"
},
"spreadsheetUrl": {
"type": "string",
"description": "URL of the resolved spreadsheet."
},
"spreadsheetName": {
"type": "string",
"description": "Resolved Google Drive spreadsheet title."
}
},
"additionalProperties": false
}
