get_symbol_context
Retrieve a C/C++ symbol's body, signature, and direct callers/callees in one call to understand its role and system fit.
Instructions
Rich one-shot context for a C/C++ symbol: body, signature, the 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.
The callers and callees include vendor/SDK code — the call graph
naturally spans project and vendor boundaries in both directions
(project → vendor API, vendor callback → project handler). Each list
is cut (callers at 50, callees at 100), and its *_total says how
many there are; *_hint names the tool that pages a cut list.
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, the direct callers and callees (each list with its total). 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: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.
Returns:
dict with: name, qualified_name, kind, file, line, signature,
docstring (raw Doxygen comment text), is_definition, callers (list,
max 50 — call and indirect references, each with its line),
callees (list, max 100 — one row for each callee and kind of
reference), source (body text),
indirect_call_sites (list, max 200 — for a field/variable symbol,
where the function pointer is invoked; for a function/method, the
calls through function pointers that it makes).
callers_total, callees_total and
indirect_call_sites_total count each whole list. When a list
is cut, callers_hint, callees_hint or
indirect_call_sites_hint names the tool that pages it.
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 an enum also returns constants (at most 200), constants_total and,
when the list is cut, constants_hint; for an enum constant, 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.
``_source_truncated`` (True) marks a body that a cap cut, as in
``get_source``.
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. ``candidates`` (max 20) lists the others
and ``candidates_total`` counts them. Give a ``qualified_name`` from
it to ask about one symbol only.
A symbol in a file outside the project root, such as an SDK header,
is returned and not refused.
On failure the dict holds only ``error`` with the reason.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name. Returns body, signature, the direct callers and callees (each list with its total). | |
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| 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 | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. 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. |