Skip to content

present_bsheet_editor

Open the existing bsheet-editor for a sheet when the user asks to see it. Pass model_name, sheet_id, and view=‘input’ or ‘output’; optionally select a tab and row window. Reuses the authorized live get_bsheet read and returns its current provenance/freshness receipt. expected_sha, expected_sheet_commit_sha, expected_run_id, expected_revision_id, and expected_branch are exact-match guards. 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='Optional opaque tab_id to return only that tab. Use tab_metadata_only=true to find tab IDs and names without reading cells. Omit or pass an empty string to return all tabs.')]No''
tab_metadata_onlyAnnotated[bool, Field(description='Return bounded tab IDs, names, and dimensions without cell values, formulas, staged edits, or formatting maps. This is useful for discovering an opaque tab_id before a bounded cell read. Mutually exclusive with row windows and comparisons.')]NoFalse
branch`Annotated[strNone, Field(description=“Branch whose cached row to read. Omit to read the model’s default-branch row — passing the default branch’s own literal name (e.g. ‘main’) reads that same row.”)]`NoNone
base_branch`Annotated[strNone, Field(description=“Optional branch/ref to diff this sheet’s cells against. When given, each populated cell’s changed field is set (true when its formula or value differs from the base_branch version; formatting-only differences don’t count) and changed_cell_count reports the total. Omit to skip the comparison — changed stays null and changed_cell_count stays null rather than a fabricated value.”)]`NoNone
compare_ref`Annotated[strNone, Field(description=“Optional branch to compare this sheet’s cell/row values against — must be one of the response’s known_branches. Input sheets gain a compare_value per populated cell; output sheets gain row_deltas keyed by row label on their row-array tab(s). Omit to skip the comparison entirely. Independent of base_branch: base_branch flags whether a cell’s formula/value changed (bool), compare_ref returns the actual comparison value/delta.”)]`NoNone
compare_previous_runAnnotated[bool, Field(description="For output sheets, compare against the immediately previous successful run on the displayed run's branch. Mutually exclusive with compare_ref. The comparison is resolved from the current workspace's run and sheet provenance; it is not a caller-supplied run id.")]NoFalse
row_startAnnotated[int, Field(ge=0, description='0-indexed first row to include for a row-array tab (requires tab_id -- ambiguous across multiple tabs). Continues a previous truncated tab window; on sparse input tabs, it also continues a truncated staged-edit window. Ignored when neither window applies.')]No0
row_limit`Annotated[intNone, Field(ge=1, description=‘Maximum rows to return for a row-array tab, starting at row_start (requires tab_id). On sparse input tabs it also caps staged edits; omit to let the server byte-bound either window. Check tabs[].window or staged_window to see what was included.’)]`NoNone
workspace_id`Annotated[strNone, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`NoNone
viewLiteral['input', 'output']Yes—
expected_sha`strNone`NoNone
expected_sheet_commit_sha`strNone`NoNone
expected_run_id`strNone`NoNone
expected_revision_id`strNone`NoNone
expected_branch`strNone`NoNone

Returns

Section titled “Returns”

Returns a structured object. Top-level fields:

  • model_name (string)
  • sheet_id (string)
  • name (string)
  • purpose (string)
  • attached_model (string)
  • branch (null)
  • latest_commit_sha (string)
  • sha (string)
  • row_count (integer)
  • tab_count (integer)
  • calculation_status (string)
  • tabs (array<object>)
  • calculation (object)
  • provenance (object)
  • generated_at (string)
  • base_branch (null)
  • changed_cell_count (null)
  • compare_ref (null)
  • tab_metadata_only (boolean)
  • compare_state (string)
  • staged (array)
  • staged_count (integer)
  • needs_recalculation (boolean)
  • model_freshness (object)
  • known_branches (array<string>)
  • known_branches_truncated (boolean)
  • header_row (null)
  • annotation_rows (array)
  • used_range (string)
  • total_rows (integer)
  • default_branch (string)
  • workspace_id (string)
  • sheet_commit_sha (string)
  • presentation (object)

See the response example below for the full payload shape.

Example

Section titled “Example”

Tool Call

Section titled “Tool Call”
{
  "name": "present_bsheet_editor",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "view": "input",
    "expected_sha": "abc1234def5678901234567890abcdef12345678",
    "expected_sheet_commit_sha": "abc1234def5678901234567890abcdef12345678",
    "expected_branch": "main"
  }
}

Response

Section titled “Response”
{
  "model_name": "forecasts",
  "sheet_id": "assumptions",
  "name": "Assumptions",
  "purpose": "input",
  "attached_model": "revenue",
  "branch": null,
  "latest_commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "row_count": 2,
  "tab_count": 1,
  "calculation_status": "clean",
  "tabs": [
    {
      "tab_id": "tab1",
      "name": "Sheet1",
      "row_count": 2,
      "column_count": 2,
      "cell_encoding": "sparse",
      "cells": {
        "A1": {
          "value": "Growth Rate",
          "formula": null,
          "format": null,
          "style": null,
          "number_format": null
        },
        "B1": {
          "value": 0.12,
          "formula": null,
          "format": null,
          "style": null,
          "number_format": "percent"
        }
      },
      "rows": [],
      "formatting": {
        "column_widths": {},
        "row_heights": {},
        "frozen_rows": 0,
        "frozen_columns": 0,
        "show_gridlines": true
      }
    }
  ],
  "calculation": {
    "engine_version": "v1",
    "status": "clean",
    "last_evaluated_at": "2026-04-28T10:00:00+00:00"
  },
  "provenance": {
    "source": "user",
    "run_id": null,
    "commit_sha": "abc1234def5678901234567890abcdef12345678",
    "branch": null,
    "output_name": null,
    "data_hash": null
  },
  "generated_at": "2026-04-28T10:00:00+00:00",
  "base_branch": null,
  "changed_cell_count": null,
  "compare_ref": null,
  "tab_metadata_only": false,
  "compare_state": "not_requested",
  "staged": [],
  "staged_count": 0,
  "needs_recalculation": false,
  "model_freshness": {
    "state": "fresh",
    "run_status": "success",
    "run_id": "66666666-6666-6666-6666-666666666666",
    "commit_sha": "abc1234def5678901234567890abcdef12345678"
  },
  "known_branches": [
    "main",
    "scenario/q2-hiring"
  ],
  "known_branches_truncated": false,
  "header_row": null,
  "annotation_rows": [],
  "used_range": "A1:B1",
  "total_rows": 1,
  "default_branch": "main",
  "workspace_id": "ws_acme",
  "sheet_commit_sha": "abc1234def5678901234567890abcdef12345678",
  "presentation": {
    "view": "input",
    "checked_at": "2026-04-28T10:00:00+00:00",
    "branch": "main",
    "sheet_sha": "abc1234def5678901234567890abcdef12345678",
    "sheet_commit_sha": "abc1234def5678901234567890abcdef12345678",
    "run_id": null,
    "revision_id": null,
    "run_state": "success",
    "model_freshness": {
      "state": "fresh",
      "run_status": "success",
      "run_id": "66666666-6666-6666-6666-666666666666",
      "commit_sha": "abc1234def5678901234567890abcdef12345678"
    }
  }
}

Notes

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