get_spreadsheet_metadata

Return metadata for a connected Google Sheet: the spreadsheet title, and for each tab the sheet ID, title, index, type, row count, and column count. Use this before write-back tools (write_gsheet) to discover available tabs and their dimensions. Target the sheet by source_name (from list_data_sources) OR spreadsheet_id — source_name is preferred for linked sheets.

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
project_name	Annotated[str, Field(description='Name of the Bridge Town project.')]	Yes	—
spreadsheet_id	`Annotated[str	None, Field(description=‘Google Spreadsheet ID from the sheet URL.’)]`	No	None
source_name	`Annotated[str	None, Field(description=‘Logical name for this Google Sheet data source, used in SQL queries.’)]`	No	None

Returns

Returns a structured object. Top-level fields:

• spreadsheet_id (string)
• title (string)
• sheets (array<object>)
• sheet_url (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "get_spreadsheet_metadata",
  "arguments": {
    "project_name": "forecasts",
    "spreadsheet_id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCDEFG"
  }
}

Response

{
  "spreadsheet_id": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCDEFG",
  "title": "FY26 Forecast",
  "sheets": [
    {
      "sheetId": 0,
      "title": "Forecast",
      "index": 0,
      "sheetType": "GRID",
      "rowCount": 1000,
      "columnCount": 26
    },
    {
      "sheetId": 12345,
      "title": "Notes",
      "index": 1,
      "sheetType": "GRID",
      "rowCount": 1000,
      "columnCount": 26
    }
  ],
  "sheet_url": "https://docs.google.com/spreadsheets/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ABCDEFG/edit"
}

Notes

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