lookup_symbol
Find C/C++ symbols by exact or prefix name via libclang. Discovers build-conditional, template-instantiated, and macro-expanded names that text search misses.
Instructions
Look up a C/C++ symbol by name via libclang index — exact or prefix
matching. Finds symbols text-based search can miss: build-conditional
code, template instantiations, macro-expanded names. Macros are
extracted via clang -dM -E during indexing so #ifdef-conditional
macros resolve correctly for the active build config. Prefer this over
search_code when you know the exact symbol name or a prefix
(uart_ finds all UART symbols). Use search_code for
keyword/concept search.
Read-only: yes. May auto-reindex stale files (non-blocking).
Args:
name: Symbol name (exact match) or prefix (set exact=False).
E.g. 'uart_init' finds the exact function; 'uart_' finds
all symbols starting with 'uart_'.
project_root: Project 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.
exact: True = exact name match, False = prefix LIKE match (default).
limit: Maximum results of one page (default 50, max 100).
offset: Skip this many results (default 0). A common method name
lives in many classes — read and write match dozens of
symbols — and this walks past the ones already seen. The page
notice names the offset to use. The order is stable (a
definition first, then the line, then the file and the USR),
thus two pages never overlap and never skip a symbol.
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[dict]: The page notice leads the answer — total, offset,
shown, more — where total counts every symbol the name
matches. Read it before you conclude that a page holds them all.
Each symbol that follows has name, qualified_name, kind, file,
line, signature, docstring, is_definition, is_template, is_virtual,
is_pure_virtual fields, and class — the class, struct or union
that declares the symbol, absent for a free function. class is
what tells two same-name methods apart at a glance.
Enum constants include enum_value
with the integer value. Macro results include kind="macro",
signature (how the macro is invoked: #define NAME,
#define NAME() or #define NAME(a, b)), is_function_like,
value (the replacement text ALONE — the parameter list is not
part of it), and expanded_value (preprocessor-resolved value).
May also include template_usr,
parent_usr, and llm_analysis ({summary, inputs, outputs}) when available. A model wrote the text in
llm_analysis, and the code did not — use it to find a symbol,
and quote signature, docstring, or get_source instead.
When no results found, may include _did_you_mean with suggested
symbol names. When no symbol matches, the list is empty — there is
then no page notice, because there is no page. An info entry
comes back for one case only: an offset past the end of an answer
that does hold rows.
**Note:** C++ constructors share their name with the enclosing
class, so ``lookup_symbol("Foo")`` may return both ``class Foo``
and ``constructor Foo::Foo()``. Use the ``kind`` field to
filter when you need a specific symbol type.
A symbol that comes from the relaxed prefix fallback carries
``_fallback: True`` — the name is not an exact match of *name*.
A list with one dict that holds an ``error`` key means that the
project has no index, or that the lookup failed. Read that key
before you read the result fields.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name. Exact match if exact=True, prefix LIKE match otherwise. E.g. 'uart_init' or 'uart_'. | |
| exact | No | True = exact name match, False = prefix LIKE match (default). | |
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum results returned (capped at 100, default 50). | |
| offset | No | Skip this many results. Pages through a name that many classes share, such as 'read' or 'write'. | |
| 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 directory. Auto-detected from CWD 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 |