create_native_sheet

Create a new native input sheet in a model, with optional starter tabs and an optional model attachment, and commit its .btsheet.json document. Always creates purpose=‘input’ — output sheet views are generated separately, not created through this tool. sheet_id is generated by the server; you cannot choose one. Starter tabs are created empty (no cells) — use update_native_sheet_cells to populate values and formulas afterwards.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model to attach the new sheet to.')]	Yes	—
name	Annotated[str, Field(description='Display name for the new sheet.', min_length=1, max_length=MAX_SHEET_NAME_LENGTH)]	Yes	—
attached_model	`Annotated[str	None, Field(description=“Optional model file this input sheet feeds (e.g. ‘revenue’). Recorded for lineage only — not validated against the model’s contract.”)]`	No	None
tabs	`Annotated[list[dict[str, Any]]	None, Field(description=“Optional starter tabs, up to 25. Each item may set name (str), row_count (int, default 100), column_count (int, default 26). Tabs are created empty (sparse cell encoding, no cells) — use update_native_sheet_cells to populate them afterwards. Defaults to a single tab named ‘Sheet1’ (100x26) when omitted.”)]`	No	None
branch	`Annotated[str	None, Field(description=“Branch to commit the new sheet to. Defaults to the model’s default branch when omitted or null.”)]`	No	None
commit_message	Annotated[str, Field(description='Git commit message. If omitted, the server generates a default message.')]	No	''

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheet_id (string)
• name (string)
• purpose (string)
• attached_model (string)
• branch (string)
• commit_sha (string)
• sha (string)
• tab_count (integer)
• tabs (array<object>)
• calculation_status (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "create_native_sheet",
  "arguments": {
    "model_name": "forecasts",
    "name": "Revenue Assumptions",
    "attached_model": "model/revenue.py",
    "tabs": [
      {
        "name": "Inputs",
        "row_count": 100,
        "column_count": 26
      }
    ]
  }
}

Response

{
  "model_name": "forecasts",
  "sheet_id": "sht_1a2b3c4d5e6f7890a1b2c3d4e5f67890",
  "name": "Revenue Assumptions",
  "purpose": "input",
  "attached_model": "model/revenue.py",
  "branch": "main",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "tab_count": 1,
  "tabs": [
    {
      "tab_id": "tab_2b3c4d5e6f7890a1b2c3d4e5f6789012",
      "name": "Inputs",
      "row_count": 100,
      "column_count": 26,
      "cell_encoding": "sparse",
      "cells": {},
      "rows": [],
      "formatting": {
        "column_widths": {},
        "row_heights": {},
        "frozen_rows": 0,
        "frozen_columns": 0,
        "show_gridlines": true
      }
    }
  ],
  "calculation_status": "clean"
}

Notes

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