explain_bsheet_cell

Return a CellExplanationPayloadV2 explanation for an input or output sheet cell with its value and v2 fields arith, confidence, target, provenance, and bounded lineage; inputs default to dependents and outputs to precedents. Inspect context first with list_bsheets, get_bsheet, get_run, or list_branches. An optional direction can request either trace without crossing models or branches; uninstrumented runs report limits honestly. Provides view: bsheet-cell-explain (ui://apps/bsheet-cell-explain) 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. Must be an input or output sheet. Omit direction to infer dependents for inputs and precedents for outputs.')]`	Yes	—
`tab_id`	`Annotated[str, Field(description='Tab to explain a cell on, as returned by get_bsheet.')]`	Yes	—
`cell_ref`	`Annotated[str, Field(description="A1 cell reference to explain, e.g. 'B7'.")]`	Yes	—
`direction`	`Annotated[Literal[‘precedents’, ‘dependents’]	None, Field(description=‘Optional lineage direction. Omit to infer dependents for input sheets and precedents for output sheets.’)]`	No	`None`
`branch`	`Annotated[str	None, Field(description=“Branch whose cached row to read. Omit to read the model’s default-branch row.”)]`	No	`None`
`workspace_id`	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	`None`

Returns

Returns a structured object. Top-level fields:

ref (string)
direction (string)
value (integer)
display (string)
unit (string)
row_label (string)
col_label (string)
sheet_name (string)
row_total (integer)
row_total_display (string)
confidence (string)
plain (string)
aside (string)
claim (string)
arith (object)
nodes (array<object>)
edges (array<array<string>>)
target (string)
waterfall (array<object>)
provenance (object)

See the response example below for the full payload shape.

Viewing the result

When MCP Apps are available, the returned payload opens in the Explain view; viewing it does not call the tool again. Inline mode uses compact map geometry and the inline branch cap. Fullscreen uses the host’s actual display mode, keeps the chosen Map or Outline lens and depth, clears any inline selection, and starts at native 100% map size. In fullscreen Map, Size offers 100% and Fit; Fit uses compact map geometry and preserves every node in the bounded graph. Size is hidden while Outline is selected. Selected-cell details, the trace note, and provenance receipt remain available through their view controls. Numeric arithmetic and waterfall details are shown when the returned payload contains them.

Example

Tool Call

{
  "name": "explain_bsheet_cell",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "sht_7890a1b2c3d4e5f67890a1b2c3d4e5f6",
    "tab_id": "tab_890a1b2c3d4e5f67890a1b2c3d4e5f67",
    "cell_ref": "C15",
    "direction": "precedents"
  }
}

Response

{
  "ref": "P&L!C15",
  "direction": "precedents",
  "value": 2688,
  "display": "$2,688",
  "unit": "USD",
  "row_label": "Gross profit (USD)",
  "col_label": "M2 · month 2",
  "sheet_name": "P&L (live from model)",
  "row_total": 3086246,
  "row_total_display": "$3,086,246",
  "confidence": "exact",
  "plain": "Gross profit in month 2 — revenue of $4,152 less COGS of $1,464.",
  "aside": "64.7% margin",
  "claim": "Traces exactly through recorded model logic to its input values.",
  "arith": {
    "terms": [
      {
        "node_id": "l2",
        "label": "Revenue",
        "display": "4,152"
      },
      {
        "node_id": "l3",
        "label": "COGS",
        "display": "1,464"
      }
    ],
    "ops": [
      "−"
    ],
    "result": {
      "node_id": "l4",
      "label": "Gross profit",
      "display": "2,688"
    }
  },
  "nodes": [
    {
      "node_id": "i1",
      "kind": "input",
      "name": "Seat price, USD/yr",
      "short": "Seat price",
      "formula": null,
      "value": "1,633.76",
      "module": "unit_economics",
      "src": "outputs/unit_economics.json",
      "conf": "exact",
      "note": null,
      "total": null
    },
    {
      "node_id": "i2",
      "kind": "input",
      "name": "COGS per seat, USD/yr",
      "short": "COGS per seat",
      "formula": null,
      "value": "576",
      "module": "unit_economics",
      "src": "outputs/unit_economics.json",
      "conf": "exact",
      "note": null,
      "total": null
    },
    {
      "node_id": "i3",
      "kind": "input",
      "name": "Seats, EoP by month",
      "short": "Seats EoP",
      "formula": null,
      "value": "M1 20 → M2 41",
      "module": "seat_dynamics",
      "src": "outputs/seat_dynamics.json",
      "conf": "exact",
      "note": null,
      "total": null
    },
    {
      "node_id": "a1",
      "kind": "assumption",
      "name": "Mid-month recognition",
      "short": "Mid-month recog",
      "formula": null,
      "value": "—",
      "module": null,
      "src": "model/projection.py:498",
      "conf": "exact",
      "note": "Revenue and COGS accrue on the average of opening and closing seats.",
      "total": null
    },
    {
      "node_id": "l1",
      "kind": "logic",
      "name": "Average seats in month",
      "short": "Average seats",
      "formula": "(opening + closing) ÷ 2",
      "value": "30.5",
      "module": "projection",
      "src": "model/projection.py:504",
      "conf": "exact",
      "note": null,
      "total": null
    },
    {
      "node_id": "l2",
      "kind": "logic",
      "name": "Revenue",
      "short": "Revenue",
      "formula": "avg seats × seat price ÷ 12",
      "value": "4,152",
      "module": "projection",
      "src": "model/projection.py:512",
      "conf": "exact",
      "note": null,
      "total": "4,581,494"
    },
    {
      "node_id": "l3",
      "kind": "logic",
      "name": "COGS",
      "short": "COGS",
      "formula": "avg seats × COGS per seat ÷ 12",
      "value": "1,464",
      "module": "projection",
      "src": "model/projection.py:516",
      "conf": "exact",
      "note": null,
      "total": "1,495,248"
    },
    {
      "node_id": "l4",
      "kind": "output",
      "name": "Gross profit",
      "short": "Gross profit",
      "formula": "revenue − COGS",
      "value": "2,688",
      "module": "projection",
      "src": "model/projection.py:521",
      "conf": "exact",
      "note": null,
      "total": "3,086,246"
    }
  ],
  "edges": [
    [
      "i3",
      "l1"
    ],
    [
      "a1",
      "l1"
    ],
    [
      "l1",
      "l2"
    ],
    [
      "i1",
      "l2"
    ],
    [
      "l1",
      "l3"
    ],
    [
      "i2",
      "l3"
    ],
    [
      "l2",
      "l4"
    ],
    [
      "l3",
      "l4"
    ]
  ],
  "target": "l4",
  "waterfall": [
    {
      "node_id": "l2",
      "label": "Revenue",
      "sub": "30.5 seats × $1,634 ÷ 12",
      "v": 4152,
      "kind": "pos"
    },
    {
      "node_id": "l3",
      "label": "COGS",
      "sub": "30.5 seats × $576 ÷ 12",
      "v": -1464,
      "kind": "neg"
    },
    {
      "node_id": "l4",
      "label": "Gross profit",
      "sub": "P&L!C15",
      "v": 2688,
      "kind": "total"
    }
  ],
  "provenance": {
    "sheet": "P&L (live from model)",
    "source": "run",
    "branch": "main",
    "run": "66666666-6666-6666-6666-666666666666",
    "commit": "abc1234def5678901234567890abcdef12345678",
    "output": "pnl_sheet.json",
    "generated": "2026-04-28T10:00:00+00:00",
    "hash": "7345de4975672615ab2acc65c06c6a9063d51d6d4dc544e9f6b4503b19269cac",
    "stale": false
  }
}

Explain prompt flow

The sheet app sends one human-readable Explain prompt to chat. On the next agent turn, call explain_bsheet_cell; the returned result renders in the dedicated bsheet-cell-explain App. The iframe does not call this tool, and the app does not add a second Ask agent action.

Getting exact lineage instead of a literal-value or inferred fallback

An uninstrumented run’s explanation is honest but minimal: on an output cell, it is a literal value recorded when the sheet was generated, with nodes/edges empty and no dependency chain behind it; on an input cell, its dependents direction falls back to an inferred or ambiguous legacy text match instead of an exact count. To get the graph shown in the example above — and to make an input cell’s “what does it drive?” answer exact — the model must opt in by writing /outputs/output_lineage.json during the run, using the OutputLineageBuilder helper, with a canonical InputSourceRef (not just a plain text source_ref) on each traced input_value/assumption call.

See Output & Input Lineage Authoring for the full model-author guide — getting the helper into your model repo, the run-id contract, worked finance examples for both directions, and the canonical input-cell-identity fields that unlock an exact (rather than best-effort) match back to a specific input sheet cell.

Notes

Module: BSheets
Requires an authenticated Bridge Town session (OAuth) or an API token.