precedents

Trace upstream dependencies — the cells a formula reads from, transitively. Default mode ‘grouped’: cells sharing a formula pattern are collapsed into labeled chunks, labeled from nearby headers. This provides a token-efficient structural view that surfaces which parameters feed into which outputs.

Switch to mode: “cells” to drill into individual cells: each node carries the formula, calculated value, and error (e.g. #DIV/0!) so you can follow error propagation to its source. Ranges referenced by formulas appear as ‘range’ nodes. If every range member is a leaf value cell, the range is collapsed into a single node with no further children.

“grouped” response shape — each node carries:

• type: “output” (computed, no dependents), “inter” (computed, has dependents), “data” (value range), “param” (single value cell)
• labels: human-readable names derived from nearby headers
• formula: the formula pattern for this chunk (with relative references)
• rootHeight: dependency distance from graph roots (parameters/data)
• leafDepth: dependency distance from graph leaves (outputs)
• precedents: dict of upstream chunk nodes keyed by their ref (omitted for leaves)
• alreadyVisited: true when this chunk was expanded elsewhere in the tree (diamond/cycle cut)
• truncated: present when traversal stopped early; reason is “maxDepth” or “maxNodes”; totalChildren reports the real count when children were cut short

“cells” response shape — each node carries:

• kind: “cell”, “range”, or “name”
• formula: the formula string, or null for value cells and range vertices
• value: the calculated value (cell and name nodes)
• errorValue: present only when the cell evaluates to a formula error
• precedents: a dict of child nodes keyed by their own ref (omitted for leaves)
• alreadyVisited: true when this node has been fully expanded elsewhere in the tree (diamond/cycle cut)
• truncated: present when traversal stopped early; reason is “maxDepth” or “maxNodes”; totalChildren reports the real count when children were cut short

Both modes use maxDepth (default 10, max 50) to bound recursion and maxNodes (default 100, max 500) as a global budget on the returned tree.

Parameter	Type		Description
reference	string	required	Cell reference to trace (e.g. ‘C1’, ‘Sheet2!A1’)
mode	"cells" | "grouped"	optional	Output mode: ‘grouped’ (default) shows chunks of cells sharing a formula pattern, labeled from nearby headers — token-efficient for structure. ‘cells’ drills into individual cells. (default: "grouped")
maxDepth	integer	optional	Maximum recursion depth through formula cells (default 10). Range expansion does not consume depth.
maxNodes	integer	optional	Total node budget for the returned tree (default 100). When the budget is exhausted, the node whose children were cut is marked truncated with totalChildren; re-query a specific cell to drill deeper.