lookup_symbol
Find C/C++ symbols by exact name or prefix using libclang indexing. Resolves build-conditional code, templates, and macros. Use when you know the symbol name; search_code for concepts.
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. exact: True = exact name match, False = prefix LIKE match (default). limit: Maximum results (default 50).
Returns:
list[dict]: Symbols with name, qualified_name, kind, file, line,
signature, docstring, is_definition, is_template, is_virtual,
is_pure_virtual fields. Enum constants include enum_value
with the integer value. Macro results include kind="macro",
value (raw definition), and expanded_value (preprocessor-
resolved value). May also include template_usr,
parent_usr, summary, inputs, outputs when available.
When no results found, may include _did_you_mean with suggested
symbol names. Empty list if not found.
**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.
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 name within the variant (multi-project). Omit for all images of the variant. | |
| limit | No | Maximum results returned (capped at 100, default 50). | |
| variant | No | Build variant name (multi-project). Omit to use default_variant or fail-closed. Use '*' for all variants. | |
| project_root | No | Project root directory. Auto-detected from CWD if omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |