trace_call_chain

The Problem With Manual Call Tracing

Tracing what a function calls, or what calls it, is one of the most common tasks in code comprehension. With grep, it goes like this: search for the function name, read the file to find the calls it makes, search for each of those functions, read their files, repeat. Each layer of depth doubles the work.

The fundamental problem is that grep finds string matches, not call relationships. A function named process appears in comments, variable names, imports, type annotations, and actual call sites. Filtering those manually is tedious and error-prone. Dynamic dispatch, re-exports, and aliased imports make it worse.

trace_call_chain builds the call graph from the AST-level symbol index, where call relationships are already resolved. One call returns the full tree to the depth you specify.

Direction: Callers vs Callees

trace_call_chain(repo="local/my-project", symbol_name="processPayment", direction="callees", depth=3)

• callees: “What does this function call?” Follow the execution path downward. Use when understanding what a function does.
• callers: “What calls this function?” Follow the dependency path upward. Use when assessing the impact of changing a function.

Both directions support configurable depth. Depth 1 gives immediate neighbors. Depth 3 is usually sufficient to understand a complete flow.

Mermaid Output

Add output_format="mermaid" to get a renderable flowchart instead of structured data.

trace_call_chain(repo="local/my-project", symbol_name="processPayment",
                 direction="callees", depth=3, output_format="mermaid")

This produces a Mermaid diagram that can be pasted directly into documentation, PR descriptions, or architecture docs. The diagram shows the call tree with labeled edges indicating the relationship between symbols.

Benchmark

Approach	Tokens	Calls	Accuracy
grep + read + repeat	2,939	7	Misses dynamic dispatch, aliased imports
trace_call_chain	1,218	1	AST-resolved, includes re-exports

The token difference (59% reduction) understates the real advantage. The native approach requires the agent to parse grep results, identify which matches are actual call sites versus string occurrences, read the target files, and repeat. Each step introduces the possibility of missing a call or following a false lead.

Why Grep Is Brittle for Call Graphs

Consider tracing the callees of validateOrder. Grep returns every file containing the string “validateOrder”, including tests, comments, type definitions, and imports. The agent must read each file to determine which references are actual call sites. Then for each callee found, the process repeats.

Three specific problems make this approach fragile:

1. Re-exports: A function exported from index.ts as a different name will not match a string search for the original name.
2. Dynamic dispatch: Method calls on interfaces or base classes cannot be traced by string matching.
3. Aliased imports: import { validateOrder as validate } means the call site uses validate(), not validateOrder().

trace_call_chain handles all three cases because it works from the resolved symbol graph, not from raw text.

Common Patterns

• Pre-refactor: Trace callees of a function you are about to change, then trace callers to see who depends on it. This gives you the full blast radius before you touch anything.
• Debugging: Trace callees to see the execution path from the entry point to the failure site.
• Documentation: Generate Mermaid diagrams of critical flows for architecture docs or onboarding materials.
• Impact assessment: Combine with impact_analysis to see not just what changed, but what the changed code reaches.