Skip to content

format_bsheet

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: update layout with the caller’s complete view_preferences and expected_version from get_bsheet.tabs[].formatting.view_preferences_version (use 0 when absent), or update semantic formatting with the complete presentation_profile and expected_profile_version from get_bsheet.tabs[].presentation_profile.version. Provides view: bsheet-editor (ui://apps/bsheet-editor) renders this tool’s result when MCP Apps are available.

Parameters

Section titled “Parameters”
NameTypeRequiredDefaultDescription
model_nameAnnotated[str, Field(description='Name of the Bridge Town model that owns the sheet.')]Yes—
sheet_idAnnotated[str, Field(description='Sheet identifier, as returned by list_bsheets.')]Yes—
tab_idAnnotated[str, Field(description='Tab identifier from get_bsheet. Input tabs accept range_updates, style_rule_updates, or tab_formatting; output tabs accept view_preferences for layout and presentation_profile for semantic formatting.')]Yes—
range_updatesAnnotated[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.')]NoField(default_factory=list)
style_rule_updatesAnnotated[list[CellStyleRule], Field(default_factory=list, max_length=256, description='Compact cell/row/column/range style patches. Each selector merges only the properties it supplies; use style.reset to clear properties. Whole rows and columns stay bounded rules and are never expanded. Requires expected_sha.')]NoField(default_factory=list)
tab_formatting`Annotated[TabFormattingNone, Field(description=‘Editable-input-only tab presentation fields to merge, such as widths or frozen panes. For style rules, style_rules replaces the compact rule set; prefer style_rule_updates for property-preserving patches; output layout uses view_preferences and output semantic formatting uses presentation_profile.’)]`NoNone
expected_shaAnnotated[str, Field(description='Expected sheet blob SHA-1 from get_bsheet. Required for compact style-rule updates or replacement. Guards input document formatting and independently guards the output artifact during profile writes.')]No''
commit_messageAnnotated[str, Field(description='Optional Git commit message.')]No''
branch`Annotated[strNone, Field(description=‘Scenario branch; null uses the sheet default.’)]`NoNone
workspace_id`Annotated[strNone, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`NoNone
presentation_profile`PresentationProfilePayloadNone`NoField(default=None, description="Complete replacement profile for a generated output tab; never combine it with range_updates, style_rule_updates, tab_formatting, or view_preferences. Read get_bsheet.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_versionintNoField(default=0, ge=0, description='Output-profile OCC version from get_bsheet.tabs[].presentation_profile.version; use 0 only when that tab has no profile. Re-read get_bsheet after a version conflict, then retry.')
delete_presentation_profileboolNoField(default=False, description='Reset an output tab to semantic defaults by deleting its saved profile. Pass the current expected_profile_version from get_bsheet; do not combine with presentation_profile, view_preferences, range_updates, style_rule_updates, or tab_formatting.')
view_preferences`McpOutputViewPreferencesRequestNone`NoField(default=None, description='Complete per-user view preferences for an output tab, including the current full column_widths and row_heights maps. Copy them from get_bsheet.tabs[].formatting, set frozen_columns to null for automatic columns or 0 for none, and set expected_version from formatting.view_preferences_version (use 0 when absent).')

Returns

Section titled “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

Section titled “Example”

Tool Call

Section titled “Tool Call”
{
  "name": "format_bsheet",
  "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

Section titled “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": "clean",
  "new_tab_id": null,
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "staged_count": null
}

Formatting a generated output tab

Section titled “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_bsheet 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_bsheet with presentation_profile (never with range_updates or tab_formatting in the same call).
  4. Call get_bsheet again and verify the effective profile/version.
{
  "name": "format_bsheet",
  "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_bsheet and retry instead of intentionally probing with a conflict.

Notes

Section titled “Notes”
  • Module: BSheets
  • Requires an authenticated Bridge Town session (OAuth) or an API token.