connect_google_sheet

Snapshot a Google Sheet into Bridge Town’s data store (ingestion phase). Reads the specified tabs (or all tabs if none given), converts each to CSV, uploads to S3 as an immutable timestamped snapshot, and updates the data source record. The sheet must be linked first via the Bridge Town web app OAuth flow — this tool reads stored credentials, not a live OAuth prompt. FRESHNESS: the snapshot is captured at call time. Models read this snapshot at run time — the live Google Sheet is NOT accessed during model execution. Call connect_google_sheet again (or configure schedule_interval_minutes) to refresh the snapshot with current sheet data. Returns: data_source_id (str) — data source UUID; spreadsheet_id (str) — Google Sheets document ID; tabs_captured (list[str]) — tab names that were snapshotted; snapshot_prefix (str|null) — S3 prefix for this snapshot batch; snapshot_taken_at (str|null) — ISO 8601 UTC timestamp of this snapshot; rows_by_tab (dict[str, int]) — row count per tab. On error: error (str) — error code; message (str); hint (str) — suggested action.

Parameters

Name	Type	Required	Default	Description
sheet_url	str	Yes	—
project_name	str	Yes	—
tab_names	`list[str]	None`	No	None
schedule_interval_minutes	`int	None`	No	None

Returns

Returns a structured object. Top-level fields:

• data_source_id (string)
• spreadsheet_id (string)
• tabs_captured (array<string>)
• snapshot_prefix (string)
• snapshot_taken_at (string)
• rows_by_tab (object)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "connect_google_sheet",
  "arguments": {
    "sheet_url": "https://docs.google.com/spreadsheets/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCDEFG/edit",
    "project_name": "forecasts",
    "tab_names": [
      "roles",
      "hires"
    ],
    "schedule_interval_minutes": 60
  }
}

Response

{
  "data_source_id": "88888888-8888-8888-8888-888888888888",
  "spreadsheet_id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCDEFG",
  "tabs_captured": [
    "roles",
    "hires"
  ],
  "snapshot_prefix": "snapshots/acme/forecasts/headcount_sheet/2026-04-28T10-00-00Z",
  "snapshot_taken_at": "2026-04-28T10:00:00+00:00",
  "rows_by_tab": {
    "roles": 12,
    "hires": 8
  }
}

Notes

• Module: Google Sheets
• Requires authentication via API token or Auth0 JWT.