recalculate_native_sheet

Recalculate every formula cell in a native sheet and commit the result. Builds the whole-sheet dependency graph (same-tab and cross-tab references), evaluates every formula in deterministic order, detects cycles (surfaced per cell as ‘#CYCLE!’), and writes each formula cell’s fresh value — or spreadsheet error label on failure — back into the sheet document.

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	—
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 get_native_sheet/create_native_sheet/write_native_sheet_cells/recalculate_native_sheet call. If the sheet was modified since, the call fails with a commit-conflict error. Omit to overwrite unconditionally.")]	No	''
branch	`Annotated[str	None, Field(description=“Branch to operate on. When omitted or null, resolves to the sheet’s default/unresolved-branch row — never the most-recently-updated row across branches. Pass explicitly to target a specific scenario branch.”)]`	No	None
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None
mode	Annotated[Literal['native', 'staged'], Field(description="Recalculation behavior. Omit or use 'native' for the established formula-only commit. Use 'staged' to atomically apply the sheet's queued staged edits, recalculate formulas, and queue its attached model once.")]	No	'native'
client_recalculate_id	`Annotated[str	None, Field(description=‘Optional stable idempotency key for an opt-in staged recalculation. Retry the same staged batch with this value, or pass the returned receipt_id.’)]`	No	None
receipt_id	`Annotated[str	None, Field(description=‘Receipt UUID from an interrupted staged recalculation. Reusing it resumes cache/run reconciliation without replaying the Git commit.’)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheet_id (string)
• branch (string)
• commit_sha (string)
• sha (string)
• calculation_status (string)
• calculation_hash (string)
• formula_cell_count (integer)
• error_cell_count (integer)
• cells (array<object>)
• workspace_id (string)
• mode (string)
• receipt_id (string)
• state (string)
• receipt_state (string)
• run_id (string)
• run_state (string)
• model_run_status (string)
• model_run_skipped_reason (null)
• applied_edit_count (integer)
• cleared_edit_count (integer)
• staged_count (integer)
• retry_guidance (string)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "recalculate_native_sheet",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "expected_sha": "abc1234def5678901234567890abcdef12345678",
    "mode": "staged",
    "client_recalculate_id": "recalc-assumptions-20260813-01"
  }
}

Response

{
  "model_name": "forecasts",
  "sheet_id": "assumptions",
  "branch": "main",
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "calculation_status": "clean",
  "calculation_hash": "9f2b1c4d5e6f7890a1b2c3d4e5f678901a2b3c4d5e6f7890a1b2c3d4e5f6789",
  "formula_cell_count": 1,
  "error_cell_count": 0,
  "cells": [
    {
      "tab_id": "tab1",
      "ref": "B5",
      "value": 1800000.0,
      "error": null
    }
  ],
  "workspace_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "mode": "staged",
  "receipt_id": "67676767-6767-6767-6767-676767676767",
  "state": "queued",
  "receipt_state": "queued",
  "run_id": "66666666-6666-6666-6666-666666666666",
  "run_state": "pending",
  "model_run_status": "started",
  "model_run_skipped_reason": null,
  "applied_edit_count": 2,
  "cleared_edit_count": 2,
  "staged_count": 0,
  "retry_guidance": "Use get_run with run_id=66666666-6666-6666-6666-666666666666 to poll model execution."
}

Notes

• Module: Native Sheets
• Requires authentication via API token or Auth0 JWT.
• Omit mode (or use mode: "native") for the original formula-only recalculation behavior; it never starts a model run.
• mode: "staged" applies the full MCP staged-edit ledger in one guarded commit, then returns a receipt. Reuse client_recalculate_id or receipt_id after an interrupted call so the commit and attached run are not duplicated.
• Output sheets remain immutable in every mode. Refresh a generated output only through its run/rematerialization workflow, never through this tool.