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/update_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. Defaults to the sheet’s cached branch when omitted or null.”)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model_name (string)
• sheet_id (string)
• commit_sha (string)
• sha (string)
• calculation_status (string)
• calculation_hash (string)
• formula_cell_count (integer)
• error_cell_count (integer)
• cells (array<object>)

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

Response

{
  "model_name": "forecasts",
  "sheet_id": "assumptions",
  "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
    }
  ]
}

Notes

• Module: Native Sheets
• Requires authentication via API token or Auth0 JWT.