lookup_symbol

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 build of the query. 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.

name matches the name or the qualified name. A name with :: that matches nothing is tried once more by its last part, kept where the qualified name ends with name: Foo::bar finds ns::Foo::bar. Macros are searched only when no symbol matches.

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: 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: 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 nothing matches, a trailing dict may hold _did_you_mean with suggested names. The symbols of the first suggestion that matches exactly then come back, each with _fallback: True — its name is NOT name. With no match and no suggestion, the list is empty and has 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. When a file that the answer names changed on disk, a dict with warning comes first.

**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 list with one dict that holds an ``error`` key means that the
project has no index, that the variant or image is wrong, or that
the lookup failed.  Read that key
before you read the result fields.