render_native_sheet_cell_explanation

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_native_sheets, get_native_sheet, get_run, or list_branches. An optional direction can request either trace without crossing models or branches; uninstrumented runs report limits honestly. Provides view: native-sheet-cell-explain (ui://apps/native-sheet-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_native_sheets. 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_native_sheet.')]	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)
• identity_state (string)
• dependent_output_count (integer)
• dependent_model_count (integer)
• value (number)
• display (string)
• unit (null)
• row_label (string)
• col_label (string)
• sheet_name (string)
• row_total (null)
• row_total_display (null)
• confidence (string)
• plain (string)
• aside (null)
• claim (string)
• warning (null)
• arith (null)
• nodes (array<object>)
• edges (array<array<string>>)
• target (string)
• waterfall (null)
• truncated (boolean)
• omitted_count (integer)
• provenance (object)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "render_native_sheet_cell_explanation",
  "arguments": {
    "model_name": "forecasts",
    "sheet_id": "assumptions",
    "tab_id": "tab1",
    "cell_ref": "B2"
  }
}

Response

{
  "ref": "Drivers!B2",
  "direction": "dependents",
  "identity_state": "exact",
  "dependent_output_count": 1,
  "dependent_model_count": 1,
  "value": 100000.0,
  "display": "100,000",
  "unit": null,
  "row_label": "Drivers",
  "col_label": "B2",
  "sheet_name": "Assumptions",
  "row_total": null,
  "row_total_display": null,
  "confidence": "exact",
  "plain": "B2 drives 1 output sheet in the latest eligible run.",
  "aside": null,
  "claim": "The map is a bounded forward walk from a recorded canonical input identity.",
  "warning": null,
  "arith": null,
  "nodes": [
    {
      "node_id": "target",
      "kind": "input",
      "name": "Drivers!B2",
      "short": "B2",
      "formula": null,
      "value": "100,000",
      "module": null,
      "src": null,
      "conf": "exact",
      "note": null,
      "total": null,
      "hop": 0,
      "stale": false,
      "stale_reason": null
    },
    {
      "node_id": "n1",
      "kind": "logic",
      "name": "Revenue calculation",
      "short": "Revenue calculation",
      "formula": null,
      "value": "—",
      "module": null,
      "src": null,
      "conf": "exact",
      "note": null,
      "total": null,
      "hop": 1,
      "stale": false,
      "stale_reason": null
    },
    {
      "node_id": "n2",
      "kind": "output",
      "name": "revenue_by_quarter.json!B2",
      "short": "B2",
      "formula": null,
      "value": "—",
      "module": null,
      "src": null,
      "conf": "exact",
      "note": null,
      "total": null,
      "hop": 2,
      "stale": false,
      "stale_reason": null
    }
  ],
  "edges": [
    [
      "target",
      "n1"
    ],
    [
      "n1",
      "n2"
    ]
  ],
  "target": "target",
  "waterfall": null,
  "truncated": false,
  "omitted_count": 0,
  "provenance": {
    "sheet": "Assumptions",
    "source": "run",
    "branch": "main",
    "run": "66666666-6666-6666-6666-666666666666",
    "commit": "abc1234def5678901234567890abcdef12345678",
    "output": null,
    "generated": "2026-04-28T10:00:00+00:00",
    "hash": null,
    "stale": false,
    "stale_reason": null
  }
}

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: Native Sheets
• Requires an authenticated Bridge Town session (OAuth) or an API token.