write_native_sheet_cells

Write only cell values, formulas, or clear operations to an editable native-sheet tab. Supports direct commits and per-cell staged edits; formatting and structural changes must use their dedicated tools. Requires Editor role and supports 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	—
`updates`	`Annotated[list[NativeSheetCellWriteInput], Field(min_length=1, max_length=500, description='Value, formula, or clear edits to apply.')]`	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:

_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": "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

{
  "_bt_tool": "write_native_sheet_cells",
  "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 authentication via API token or Auth0 JWT.