get_symbol_context
Get a C/C++ symbol's body, signature, and all direct callers and callees in one response. Understand its role and connections without multiple queries.
Instructions
Rich one-shot context for a C/C++ symbol: body, signature, all direct callers and callees. Answers "what does this do and how does it fit in the system?" in a single response — libclang powers the call graph, not regex. Falls back to macro display when the symbol is not found.
Prefer this over get_source when you also need callers, callees,
indirect call sites, or LLM analysis — all returned in a single call.
If you only need the raw function body (no metadata), get_source is
slightly faster. For transitive call-graph exploration use
find_all_callers_recursive or find_callees_recursive.
Returns ALL callers and callees including vendor/SDK code — the call graph naturally spans project and vendor boundaries in both directions (project → vendor API, vendor callback → project handler).
The body is ifdef-filtered, the same as in get_source: a line of
an inactive #if branch comes back blank and the line numbers do not
move. source_origin says whether the text is the filtered copy
("index") or the file itself ("disk", every branch present).
Read-only. No side effects.
Args: name: Symbol name. Returns body, signature, all direct callers and callees. 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. 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:
dict with: name, qualified_name, kind, file, line, signature,
docstring (raw Doxygen comment text), is_definition, callers (list),
callees (list), source (body text),
indirect_call_sites (list, for field/variable symbols — where the
function pointer is actually invoked).
For field and variable symbols that have function pointer type,
also includes resolution: {assignments_found, call_sites_found,
resolved, note} indicating whether assignments and call sites are
linked (Phase 3). resolved=False with a note when parts are
missing — LLM can detect uncertainty.
For enums also returns constants and enum_value.
For macros returns kind="macro", signature (#define NAME
or #define NAME(a, b)), is_function_like, value (the
replacement text ALONE) and expanded_value
(preprocessor-resolved).
When LLM analysis has been generated (fw-context index --analyze),
includes llm_analysis: {summary, inputs, outputs, model, analyzed_at}
with a structured description of the symbol's purpose, parameters, and
return values/side effects.
When the file changed after the last index run, the dict adds
``stale`` (True) and ``stale_warning`` (str), and ``source_origin``
tells where the body comes from: ``"disk"`` when the symbol did not
move, ``"index"`` when it did. The callers and callees come from the
index in all cases, thus a stale dict can hold an incomplete list.
The dict also carries the libclang flags of the symbol:
is_virtual, is_pure_virtual, is_template, parent_usr, and
template_usr. For a virtual method it adds ``overrides`` (the base
methods that this method overrides) and ``overridden_by`` (the
derived methods that override it) — use these two before you change
a virtual method.
An ``ambiguous_warning`` key means that *name* matched more than one
symbol, such as two classes with a method of the same name. Every
part of this answer — body, callers and callees — is about the ONE
symbol that the key names, and the key lists the others. Give the
full qualified name to ask about one symbol only.
On failure the dict holds ``error`` with the reason. One failure
carries more than that: when the best match for *name* is in a file
outside the project root, the dict also holds ``candidates``,
``candidates_total`` and a ``hint``. Read them — a common name
matches many symbols, and one of the others is often inside the
project.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name. Returns body, signature, all direct callers and callees. | |
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| 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. | |
| 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. |