format_native_sheet

Apply range-level cell styles, number formats, or tab presentation settings without changing values, formulas, or sheet structure. Requires Editor role and expected_sha OCC.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model that owns the sheet.')]	Yes	—
sheet_id	Annotated[str, Field(description='Sheet identifier, as returned by list_native_sheets.')]	Yes	—
tab_id	Annotated[str, Field(description='Editable tab identifier, as returned by get_native_sheet.')]	Yes	—
range_updates	Annotated[list[NativeSheetRangeFormatInput], Field(default_factory=list, max_length=20, description='Rectangular style and number-format patches.')]	No	Field(default_factory=list)
tab_formatting	`Annotated[TabFormatting	None, Field(description=‘Tab presentation fields to merge, such as widths or frozen panes.’)]`	No	None
expected_sha	Annotated[str, Field(description='Expected sheet blob SHA-1 for optimistic concurrency.')]	No	''
commit_message	Annotated[str, Field(description='Optional Git commit message.')]	No	''
branch	`Annotated[str	None, Field(description=‘Scenario branch; null uses the sheet default.’)]`	No	None
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• _bt_tool (string)
• model_name (string)
• sheet_id (string)
• tab_id (string)
• branch (string)
• commit_sha (string)
• sha (string)
• updated_cells (integer)
• range_formatted_cells (integer)
• calculation_status (string)
• new_tab_id (null)
• workspace_id (string)
• staged_count (null)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "format_native_sheet",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "tab_id": "tab1",
    "range_updates": [
      {
        "start_ref": "B2",
        "end_ref": "B5",
        "style": {
          "bold": true
        }
      }
    ],
    "expected_sha": "abc1234def5678901234567890abcdef12345678"
  }
}

Response

{
  "_bt_tool": "format_native_sheet",
  "model_name": "forecasts",
  "sheet_id": "assumptions",
  "tab_id": "tab1",
  "branch": "main",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "updated_cells": 0,
  "range_formatted_cells": 4,
  "calculation_status": "dirty",
  "new_tab_id": null,
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "staged_count": null
}

Notes

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