Skip to content

update_bsheet_cells

Write cell values, formulas, clear operations, or explicit semantic roles (parameter, annotation, label) to an editable native-sheet tab. Each input edit commits with its automatic calculation workflow and returns a receipt for retry or Undo. An append-only tab_resize, range formatting, or tab presentation change may be combined with cell updates in the same atomic commit; content edits still calculate and request the attached model. 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='Editable tab identifier, as returned by get_bsheet.')]Yes—
updates`Annotated[list[NativeSheetCellWriteInput], Field(min_length=1, max_length=500, description=‘Value, formula, role, or clear edits. role is parameterannotationlabel; omit it to preserve classification or pass null to unclassify.’)]`Yes
range_updatesAnnotated[list[NativeSheetRangeFormatInput], Field(max_length=20, description='Optionally apply bounded range style/number-format patches in the same atomic commit as cell content edits.')]NoField(default_factory=list)
tab_formatting`Annotated[TabFormattingNone, Field(description=‘Optionally merge tab presentation settings in the same atomic commit as cell content edits.’)]`NoNone
tab_resize`Annotated[TabResizeInputNone, Field(description=‘Optionally grow tab_id in the same atomic write as appended cell updates. Object with row_count (int) and/or column_count (int); growth is append-only and shrink requests are rejected. Requires tab_id.’)]`NoNone
client_edit_id`Annotated[strNone, Field(description=‘Optional idempotency key for this edit. Reuse it when retrying the same request so the write and model run are not duplicated.’)]`NoNone
undo_receipt_id`Annotated[strNone, Field(description=‘Receipt id returned for your own recent automatic input edit. When set, updates must be the exact inverse batch returned with that receipt; the server verifies authorship and current cell contents before committing it.’, min_length=1, max_length=128)]`NoNone
expected_shaAnnotated[str, Field(description='Expected sheet blob SHA-1 for optimistic concurrency.')]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

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 (integer)
  • operation_id (string)
  • receipt_id (string)
  • calculation_state (string)
  • run_requested (boolean)
  • run_intent (object)
  • run_id (string)
  • edit_saved (boolean)
  • retry_hint (null)
  • client_edit_id (string)
  • undo_receipt_id (string)
  • undo_tab_id (string)
  • undo_updates (array<object>)
  • committed_at (string)

See the response example below for the full payload shape.

Example

Section titled “Example”

Tool Call

Section titled “Tool Call”
{
  "name": "update_bsheet_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",
    "client_edit_id": "edit_revenue_assumptions_01"
  }
}

Response

Section titled “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": "clean",
  "new_tab_id": null,
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "staged_count": 0,
  "operation_id": "op_edit_revenue_assumptions_01",
  "receipt_id": "receipt_edit_revenue_assumptions_01",
  "calculation_state": "clean",
  "run_requested": true,
  "run_intent": {
    "requested": true,
    "run_id": "66666666-6666-6666-6666-666666666666",
    "state": "success"
  },
  "run_id": "66666666-6666-6666-6666-666666666666",
  "edit_saved": true,
  "retry_hint": null,
  "client_edit_id": "edit_revenue_assumptions_01",
  "undo_receipt_id": "undo_revenue_assumptions_01",
  "undo_tab_id": "tab1",
  "undo_updates": [
    {
      "a1_ref": "B2",
      "value": 1500000
    },
    {
      "a1_ref": "B5",
      "clear": true
    }
  ],
  "committed_at": "2026-04-28T10:00:00+00:00"
}

Notes

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