update_native_sheet_cells

Batch-update cells in one tab, merge tab-level formatting (freeze rows/columns, gridline visibility, column widths/row heights), and/or append a new tab to a native sheet, committing the result. Each call is a direct, explicit commit — MCP tool calls always commit immediately, there is no staged-draft/autosave state to opt into.

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 or create_native_sheet.')]	Yes	—
tab_id	`Annotated[str	None, Field(description=‘Tab to update, as returned by get_native_sheet or create_native_sheet. Required when updates or tab_formatting is provided; omit when the call only adds a new tab via new_tab. Must be a sparse-encoded (input) tab; row-array (generated output) tabs cannot be edited this way.’)]`	No	None
updates	`Annotated[list[dict[str, Any]]	None, Field(description=“Cell updates to apply, 0-500 per call. Each item must include a1_ref (str, e.g. ‘B5’) and optionally value, formula, format (preset), style (bold/italic/colors/align/borders/decimals), number_format, or clear=true. format/style/number_format merge onto the cell when omitted. May be empty (or omitted) if the call only sets tab_formatting and/or new_tab.”)]`	No	None
tab_formatting	`Annotated[dict[str, Any]	None, Field(description=“Tab-level presentation settings to merge onto tab_id’s existing formatting: column_widths (dict[str, int]), row_heights (dict[str, int]), frozen_rows (int), frozen_columns (int), show_gridlines (bool). Only the fields present in this object are changed; omitted fields keep their current value. Requires tab_id.”)]`	No	None
new_tab	`Annotated[dict[str, Any]	None, Field(description=“Append a new, empty sparse tab to the sheet. Object with name (str, required), row_count (int, default 100), column_count (int, default 26). The server generates the new tab’s id, returned as new_tab_id — use it as tab_id in a follow-up call to populate cells.”)]`	No	None
expected_sha	Annotated[str, Field(description="Expected blob SHA-1 (40 hex chars) of the sheet's .btsheet.json, for optimistic concurrency control -- pass the sha returned by a prior create_native_sheet/update_native_sheet_cells call. If the sheet was modified since, the call fails with a commit-conflict error. Omit to overwrite unconditionally.")]	No	''
commit_message	Annotated[str, Field(description='Git commit message. If omitted, the server generates a default message.')]	No	''
branch	`Annotated[str	None, Field(description=“Branch to operate on. Defaults to the sheet’s cached branch when omitted or null.”)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheet_id (string)
• tab_id (string)
• commit_sha (string)
• sha (string)
• updated_cells (integer)
• calculation_status (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "update_native_sheet_cells",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "tab_id": "tab1",
    "updates": [
      {
        "a1_ref": "B2",
        "value": 1800000
      },
      {
        "a1_ref": "B5",
        "formula": "=SUM(B2:B4)"
      }
    ],
    "expected_sha": "abc1234def5678901234567890abcdef12345678"
  }
}

Response

{
  "model_name": "forecasts",
  "sheet_id": "assumptions",
  "tab_id": "tab1",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "updated_cells": 2,
  "calculation_status": "dirty"
}

Notes

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