list_native_sheets

Discover native (Bridge-Town-authored) input sheets and output sheet views attached to a model. Returns cheap cached summary counts (row_count, tab_count, calculation_status) — no cell data, no per-sheet Git read — plus a best-effort cache_state freshness flag from one batched Git check per distinct branch among the results (never one Git call per sheet).

read-only · idempotent

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model whose native sheets to list.')]	Yes	—
purpose	Annotated[Literal['', 'input', 'output'], Field(description="Optional purpose filter: 'input' or 'output'. Omit or pass an empty string for no filter.")]	No	''
branch	`Annotated[str	None, Field(description=“Optional branch filter — scope the listing to one branch’s rows. Omit to list every branch’s rows together (each entry’s own branch field identifies which branch it came from). The model’s default branch’s own literal name (e.g. ‘main’) filters the same rows as omitting branch entirely.”)]`	No	None
limit	Annotated[int, Field(ge=1, le=200, description='Maximum native sheets per page (default 200).')]	No	200
cursor	`Annotated[str	None, Field(description=‘Opaque continuation cursor from a previous list_native_sheets response.’)]`	No	None
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheets (array<object>)
• total_count (integer)
• truncated (boolean)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "list_native_sheets",
  "arguments": {
    "model_name": "forecasts"
  }
}

Response

{
  "model_name": "forecasts",
  "sheets": [
    {
      "sheet_id": "assumptions",
      "name": "Assumptions",
      "purpose": "input",
      "attached_model": "model/revenue.py",
      "branch": "main",
      "latest_commit_sha": "abc1234def5678901234567890abcdef12345678",
      "row_count": 42,
      "tab_count": 2,
      "calculation_status": "clean",
      "updated_at": "2026-04-28T10:00:00+00:00"
    },
    {
      "sheet_id": "q1-output",
      "name": "Q1 Output View",
      "purpose": "output",
      "attached_model": null,
      "branch": "main",
      "latest_commit_sha": "abc1234def5678901234567890abcdef12345678",
      "row_count": 120,
      "tab_count": 1,
      "calculation_status": "dirty",
      "updated_at": "2026-04-28T10:00:00+00:00"
    }
  ],
  "total_count": 2,
  "truncated": false
}

Notes

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