explain_symbol
Get a plain-English explanation of any C/C++ symbol: its purpose, inputs, outputs, and side effects. Uses pre-computed analysis when available, with on-demand LLM fallback.
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: 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: {name, kind, file, line, signature, explanation, llm_analysis
(if pre-computed)}, plus source/explain_prompt on fallback. 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.
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 and lists the
others. Give the full qualified name to ask about one symbol only.
It is separate from ``warning``, which the LLM error paths use.
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 to explain. E.g. 'uart_init', 'ModemMsg::send'. | |
| 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. | |
| context_lines | No | Lines of source context around the symbol definition. |