find_all_callers_recursive
Trace every direct and indirect caller of a C/C++ function across the full call graph, including function pointers, constructors, and dispatch edges, to assess the impact of a change before refactoring.
Instructions
Find all transitive C/C++ callers — who calls name, directly or indirectly, through the libclang call graph including function-pointer edges, implicit constructors, and synthetic dispatch edges. libclang-powered: follows function-pointer assignments and ISR vector registrations across the full call tree.
Use for impact analysis: "if I change this function, how far does the
ripple go?" Returns callers at depth 1 (direct), depth 2 (callers of
callers), up to max_depth (default 5). Results are deduplicated —
each caller appears once at its shortest distance to the target.
Edge types traversed: Includes call, indirect (function
pointers / ISRs), implicit_construct (constructors reachable through
file-scope global objects), and dispatch (synthetic edges through
event loops and thread starts).
Limitation — ambiguous name resolution: When a source-line fallback
cannot disambiguate which method is called (e.g. attach() matching
both Timeout::attach and SerialBase::attach), the edge is
conservatively omitted to avoid false callers. If you suspect a
missing caller, verify with search_bodies("target_name") and
find_indirect_targets.
For a flat, single-level caller list use find_callers (faster).
For the reverse direction use find_callees_recursive.
Read-only. No side effects. Requires the reference index
(fw-context index — refs on by default). BFS from the target
outward; performance scales with call-graph fan-out.
Args: name: Symbol name to find transitive callers of. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. max_depth: Maximum BFS depth for transitive search (default 5). limit: Maximum results (default 50). variant: Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. image: Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.
Returns: list of dicts, each with: name (str — the caller), qualified_name (str), kind (str), signature (str), depth (int — distance from the target), file (str — absolute).
This tool gives no line, because one caller can hold several call
sites. For the line of each call use ``find_callers`` on the name
that this tool reports.
When *name* matches more than one symbol, such as two classes with
a method of the same name, the answer holds the callers of all of
them. A ``warning`` dict then comes first and names the symbols,
and each result carries ``target_qualified_name``, which tells the
symbol that it calls. Give the full qualified name to ask about
one symbol only.
Never empty: one dict with ``error`` (cannot resolve) or ``info``
(no results) replaces the results. Check both keys first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name to find transitive callers of. | |
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum results (default 50). | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. | |
| max_depth | No | Maximum BFS depth for transitive search (default 5). | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |