explain_symbol
Explain any C/C++ symbol in plain English with libclang-aware analysis, returning its purpose, inputs, outputs, and side effects from precomputed or on-demand LLM data.
Instructions
Explain what a C/C++ symbol does in plain English — libclang-aware
analysis. Uses pre-computed LLM analysis when available (instant),
falls back to on-demand LLM. Falls back to macro explanation when
the name matches a #define.
Read-only. No side effects — uses pre-computed LLM analysis when available
(instant, generated during fw-context index --analyze), falls back to
calling an LLM on-demand. Returns the symbol's purpose, inputs, outputs,
and side effects.
For raw source code use get_source. For symbol metadata without
explanation use lookup_symbol. For body + callers + callees use
get_symbol_context.
Args:
name: Symbol name to explain. E.g. uart_init, ModemMsg::send.
project_root: Project root directory. 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.
context_lines: Lines of source context around the symbol definition
(default 40, max 200). Only used when no pre-computed analysis exists.
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: {name, kind, file, line, signature, explanation, llm_analysis
(if pre-computed)}. With no pre-computed analysis and no local
LLM (disabled), the dict holds explain_prompt and no
explanation. Macro fallback returns kind="macro", signature (as #define NAME
or #define NAME(a, b)), is_function_like, value (the
replacement text ALONE), and expanded_value.
A ``warning`` key means that the local LLM gave no explanation —
the request timed out, or the model is not available. The dict then
holds ``source`` and ``explain_prompt``: read the source, and answer
the prompt yourself.
When the file changed after the last index run, the dict adds
``stale`` (True) and ``stale_warning`` (str). ``stale_warning`` is
separate from ``warning``, which the LLM error paths use. A symbol
that moved gives its indexed body, not the code that now sits at the
stored line number.
The on-demand path reads ``context_lines`` around the symbol from
the DISK. That window is NOT ifdef-filtered: it holds every
``#if`` branch. This tool gives no ``source_origin``.
An ``ambiguous_warning`` key means that *name* matched more than one
symbol, such as two classes with a method of the same name. This
answer is about ONE of them, and the key names it. ``candidates``
(max 20) lists the others and ``candidates_total`` counts them.
Give a ``qualified_name`` from it to ask about one symbol only.
It is separate from ``warning``, which the LLM error paths use.
A symbol in a file outside the project root, such as an SDK
header, is explained and not refused.
On failure the dict holds only ``error`` with the reason.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name to explain. E.g. 'uart_init', 'ModemMsg::send'. | |
| 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. | |
| context_lines | No | Lines of source context around the symbol definition (1-200). |