Skip to content

refresh_output_sheet_view

Re-materialize an existing output sheet view from a newer successful run of the same model, replacing its tab content and provenance while keeping the same sheet_id and tab_id. Commits to the sheet’s existing Git path — prior versions remain readable from Git history, unlike deleting and recreating the sheet. Provides view: native-sheet-editor (ui://apps/native-sheet-editor) renders this tool’s result when MCP Apps are available.

Parameters

Section titled “Parameters”
NameTypeRequiredDefaultDescription
presentation_modeAnnotated[Literal['preserve', 'merge', 'replace', 'reset'], Field(description='Durable profile operation: preserve the saved profile (default), merge supplied rules, replace it with a complete supplied profile, or reset it so refreshed schema and semantic defaults apply.')]No'preserve'
presentation_profile`Annotated[PresentationProfilePayloadNone, Field(description=‘Validated workspace-shared selector profile for merge/replace. Omit it for preserve or reset; merge and replace require it when no column_hints or row_formats are supplied.’)]`NoNone
model_nameAnnotated[str, Field(description='Name of the Bridge Town model that owns the sheet and the run.')]Yes—
sheet_idAnnotated[str, Field(description='sheet_id of the existing output sheet view to refresh, as returned by create_output_sheet_view, list_native_sheets, or get_native_sheet.')]Yes—
run_idAnnotated[str, Field(description='UUID (or unique prefix) of the newer completed model run to re-materialize the sheet view from.')]Yes—
output_name`Annotated[strNone, Field(description=“Name of the run output to render as the refreshed sheet. Defaults to the sheet’s current output_name (from its provenance) when omitted. Resolves with or without a trailing ‘.json’ when unambiguous.”)]`NoNone
column_hints`Annotated[list[ColumnFormatHint]None, Field(description=‘Per-column presentation hints; refresh preserves the workspace-shared profile and applies these hints when supplied.’)]`NoNone
emphasize_rows`Annotated[list[int]None, Field(description=“0-based data-row indices (header row excluded) to bold-emphasize — same contract as create_output_sheet_view’s emphasize_rows.”)]`NoNone
frozen_label_columnAnnotated[bool, Field(description='Freeze the first column, in addition to the header row.')]NoFalse
row_formats`Annotated[list[RowFormatHint]None, Field(description=“Per-row presentation hints, keyed by the exact value of the row’s first column — same contract as create_output_sheet_view’s row_formats. Wins over column_hints for a matched row.”)]`NoNone
branch`Annotated[strNone, Field(description=“Branch for the sheet view. Defaults to the model’s unresolved branch; pass the exact branch for scenario-specific refreshes.”)]`NoNone
expected_shaAnnotated[str, Field(description="Expected blob SHA-1 (40 hex chars) of the sheet's current .btsheet.json, for optimistic concurrency control -- pass the sha returned by a prior create_output_sheet_view/refresh_output_sheet_view/get_native_sheet call. If the sheet was modified since, the call fails with a commit-conflict error. Omit to overwrite unconditionally.")]No''
commit_messageAnnotated[str, Field(description='Git commit message. If omitted, the server generates a default message.')]No''
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)
  • name (string)
  • purpose (string)
  • run_id (string)
  • run_branch (string)
  • run_commit_sha (string)
  • previous_run_id (string)
  • output_name (string)
  • branch (null)
  • commit_sha (string)
  • sha (string)
  • tab_id (string)
  • tab_count (integer)
  • row_count (integer)
  • column_count (integer)
  • data_hash (string)
  • presentation_hash (string)
  • presentation_profile (object)
  • profile_version (integer)
  • generated_at (string)
  • calculation_status (string)

See the response example below for the full payload shape.

Example

Section titled “Example”

Tool Call

Section titled “Tool Call”
{
  "name": "refresh_output_sheet_view",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
    "run_id": "77777777-7777-4777-8777-777777777777"
  }
}

Response

Section titled “Response”
{
  "model_name": "forecasts",
  "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
  "name": "revenue_by_quarter (run 66666666)",
  "purpose": "output",
  "run_id": "77777777-7777-4777-8777-777777777777",
  "run_branch": "main",
  "run_commit_sha": "abc1234def5678901234567890abcdef12345678",
  "previous_run_id": "66666666-6666-6666-6666-666666666666",
  "output_name": "revenue_by_quarter",
  "branch": null,
  "commit_sha": "abc1234def5678901234567890abcdef12345678",
  "sha": "abc1234def5678901234567890abcdef12345678",
  "tab_id": "tab_890a1b2c3d4e5f67890a1b2c3d4e5f67",
  "tab_count": 1,
  "row_count": 6,
  "column_count": 3,
  "data_hash": "a1b2c3d4e5f678901a2b3c4d5e6f789012b3c4d5e6f7890a1b2c3d4e5f67890",
  "presentation_hash": "b1c2d3e4f5a678901b2c3d4e5f6a789012c3d4e5f6a7890b1c2d3e4f5a678901",
  "presentation_profile": {
    "schema_version": 1,
    "version": 4,
    "rules": [
      {
        "selector_type": "column",
        "selector": "Amount",
        "format": {
          "kind": "currency",
          "currency_code": "GBP"
        }
      }
    ]
  },
  "profile_version": 4,
  "generated_at": "2026-04-28T10:00:00+00:00",
  "calculation_status": "clean"
}

Presentation modes during refresh

Section titled “Presentation modes during refresh”

presentation_mode controls the saved profile independently of the immutable data rematerialization:

  • preserve (default): keep the saved profile; omit presentation_profile.
  • merge: merge the supplied rules into the saved rules.
  • replace: replace all saved rules with the supplied complete profile.
  • reset: delete the saved profile so refreshed schema and semantic defaults apply; omit presentation_profile.
{"presentation_mode": "preserve"}
{"presentation_mode": "merge", "presentation_profile": {"schema_version": 1, "rules": [{"selector_type": "column", "selector": "Amount", "format": {"kind": "currency", "currency_code": "EUR"}}]}}
{"presentation_mode": "replace", "presentation_profile": {"schema_version": 1, "rules": [{"selector_type": "column", "selector": "Amount", "format": {"kind": "currency", "currency_code": "AED", "currency_display": "code"}}]}}
{"presentation_mode": "reset"}

These fragments are added to the normal model_name, sheet_id, run_id, and expected_sha arguments. Read the returned effective profile/version, then call get_native_sheet to verify the refreshed tab.

Notes

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