format_native_sheet

Format one native-sheet tab without changing values or formulas. For editable input tabs, use range_updates and/or tab_formatting with expected_sha. Generated output cells are immutable: format an output tab only by passing the complete presentation_profile plus expected_profile_version read from get_native_sheet.tabs[].presentation_profile.version (use 0 when absent), or delete_presentation_profile=true to reset semantic defaults. Provides view: native-sheet-editor (ui://apps/native-sheet-editor) renders this tool’s result when MCP Apps are available.

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='Tab identifier from get_native_sheet. Input tabs accept range_updates or tab_formatting; output tabs accept only presentation_profile operations.')]	Yes	—
range_updates	Annotated[list[NativeSheetRangeFormatInput], Field(default_factory=list, max_length=20, description='Editable-input-only rectangular style and number-format patches; never use against generated output cells. number_format accepts a structured NumberFormatSpec; currency formatting requires an active uppercase ISO 4217 currency_code.')]	No	Field(default_factory=list)
tab_formatting	`Annotated[TabFormatting	None, Field(description=‘Editable-input-only tab presentation fields to merge, such as widths or frozen panes; use presentation_profile for an output tab.’)]`	No	None
expected_sha	Annotated[str, Field(description='Expected sheet blob SHA-1 from get_native_sheet. Guards input document formatting and independently guards the output artifact during profile writes.')]	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
presentation_profile	`PresentationProfilePayload	None`	No	Field(default=None, description="Complete replacement profile for a generated output tab; never combine it with range_updates or tab_formatting. Read get_native_sheet.tabs[].presentation_profile first, preserve or modify its bounded rules, and pass that object's version as expected_profile_version. Use 0 only when presentation_profile is absent.")
expected_profile_version	int	No	Field(default=0, ge=0, description='Output-profile OCC version from get_native_sheet.tabs[].presentation_profile.version; use 0 only when that tab has no profile. Re-read get_native_sheet after a version conflict, then retry.')
delete_presentation_profile	bool	No	Field(default=False, description='Reset an output tab to semantic defaults by deleting its saved profile. Pass the current expected_profile_version from get_native_sheet; do not combine with presentation_profile, range_updates, or tab_formatting.')

Returns

Returns a structured object. Top-level fields:

• 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

{
  "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
}

Formatting a generated output tab

range_updates and tab_formatting are only for editable input tabs. Generated output cells remain immutable, but their bounded sidecar presentation profile can be replaced through this same tool:

1. Call get_native_sheet with the output sheet_id and tab_id.
2. Read tabs[0].presentation_profile. Preserve or modify its complete rules array and use its version as expected_profile_version; use version 0 only when the field is absent.
3. Call format_native_sheet with presentation_profile (never with range_updates or tab_formatting in the same call).
4. Call get_native_sheet again and verify the effective profile/version.

{
  "name": "format_native_sheet",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
    "tab_id": "tab_890a1b2c3d4e5f67890a1b2c3d4e5f67",
    "expected_sha": "abc1234def5678901234567890abcdef12345678",
    "expected_profile_version": 4,
    "presentation_profile": {
      "schema_version": 1,
      "rules": [
        {
          "selector_type": "column",
          "selector": "Amount",
          "format": {
            "kind": "currency",
            "currency_code": "GBP",
            "currency_display": "symbol",
            "negative_style": "parentheses",
            "zero_style": "dash"
          }
        }
      ]
    }
  }
}

Use the same structured shape with currency_code set to USD, EUR, or AED; use the structured currency format for every non-default currency. To reset the saved profile to semantic defaults, omit presentation_profile and pass delete_presentation_profile: true with the current profile version. A stale or omitted version returns native-sheet-profile-version-conflict; re-read get_native_sheet and retry instead of intentionally probing with a conflict.

Notes

• Module: Native Sheets
• Requires an authenticated Bridge Town session (OAuth) or an API token.