Skip to main content
Looks up rows in a Google Spreadsheet by matching values in one or more columns, and returns either the complete matching rows or values from a specific column. Display name “Google Sheets Lookup”. Off by default.

​
Authentication and enablement

Requires a workspace Google Sheets OAuth integration. access_token is injected (x-variable-service: google_sheets) and is never chosen by the model. Enable the tool on the agent and bind the integration.

​
Inputs

  • spreadsheet_id (required): the spreadsheet ID from the URL.
  • sheet_name (optional): defaults to the first sheet. Ignored when gid is set.
  • gid (optional): the tab id (the number after #gid= in the spreadsheet URL). Takes precedence over sheet_name when both are set.
  • match_criteria (required unless raw is true): column/value filters, AND’d across criteria, OR’d within a criterion’s values. Supports exact, prefix, and fuzzy matching via matching_strategy / per-criterion match_mode.
  • return_column (optional): extract one column’s value per match into found_values instead of returning full rows.
  • raw (optional, default false): skip match_criteria and header extraction entirely, and return every row of the tab unfiltered in raw_rows — an array of arrays, cell values in column order, row 0 not assumed to be a header row. Use this for sheets whose structure can’t be expressed as column-value filters (e.g. grouping/header rows interleaved with data rows), typically feeding the raw grid into a python_code_tool that parses the structure itself.

​
Output

Filtered mode: columns (headers), found_rows (matched rows keyed by header name) or found_values (when return_column is set), matched_values, row_numbers, match_count, match_type. Raw mode (raw: true): raw_rows only — every row, unfiltered, in sheet order. columns/found_rows/found_values are empty in this mode.

​
Limits and side effects

  • Read-only; no writes.
  • Filtered mode does one uncapped values.get call per invocation.
  • Raw mode uses a capped fetch (15 MB) and refuses cleanly on an oversized response, since it always returns the whole tab rather than a filtered subset — filtered mode is unaffected by this cap.

​
Expected errors

  • Missing/invalid Sheets integration token.
  • Spreadsheet not found, or has no sheets.
  • gid set but no tab with that id exists in the spreadsheet.
  • sheet_name set but no tab matches it (exact or fuzzy).
  • match_criteria empty when raw is not set.
  • Referenced column not found, or out of range.