write_native_sheet_cells

Write cell values, formulas, clear operations, or explicit semantic roles (parameter, annotation, label) to an editable native-sheet tab. Values, formulas, and clears support direct commits or per-cell staged edits; semantic-role changes require a direct commit. Formatting and structural changes must use their dedicated tools. Requires Editor role and supports expected_sha OCC. 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='Editable tab identifier, as returned by get_native_sheet.')]`	Yes	—
`updates`	`Annotated[list[NativeSheetCellWriteInput], Field(min_length=1, max_length=500, description=‘Value, formula, role, or clear edits. role is parameter	annotation	label; omit it to preserve classification or pass null to unclassify.’)]`	Yes
`mode`	`Annotated[Literal['direct', 'staged'], Field(description='Commit immediately, or stage cell edits for a later recalculation.')]`	No	`'direct'`
`client_edit_id`	`Annotated[str	None, Field(description=‘Optional idempotency key for staged edits.’)]`	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:

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": "write_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",
  "branch": "main",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "updated_cells": 2,
  "range_formatted_cells": 0,
  "calculation_status": "dirty",
  "new_tab_id": null,
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "staged_count": null
}

Notes

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