recalculate_bsheet

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. Provides view: bsheet-editor (ui://apps/bsheet-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_bsheets.')]	Yes	—
expected_sha	Annotated[str, Field(description='Expected blob SHA-1 (40 hex chars) of the current sheet document, for optimistic concurrency control. Omit to overwrite unconditionally.')]	No	''
branch	`Annotated[str	None, Field(description=“Scenario branch; null uses the sheet’s default branch.”)]`	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)
• 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)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "recalculate_bsheet",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "expected_sha": "abc1234def5678901234567890abcdef12345678"
  }
}

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"
}

Notes

• Module: BSheets
• Requires an authenticated Bridge Town session (OAuth) or an API token.
• This is a formula-only repair operation. It commits recalculated cell values but never starts a model run.
• Output sheets remain immutable. Create or refresh a generated output view through its run/rematerialization workflow.