find_variables
Find C/C++ variables by name or prefix and trace which functions read or write them through the call graph to reveal shared state and side effects.
Instructions
Find C/C++ variables by name or prefix and trace who reads or
writes them through the call graph. libclang-powered: splits
variables into global (varglobal — file/namespace/class-scope)
and local (varlocal — inside a function body).
Each result includes a type signature (bool timeSet,
const IPAddress modbus_ip), the enclosing function for locals
("<file scope>" for globals), and a references list showing
every function that reads or writes the variable — the same
ref_kind values as find_references ("call", "ref",
"member").
Use when you need to understand shared state, find who modifies a
global variable, trace side effects, or distinguish important globals
from loop counters. For general symbol search use search_code or
lookup_symbol. For all references to a specific variable
(including reads in expressions), use find_references.
This tool is the way to a LOCAL variable: search_code drops the
varlocal kind, because a local matches every topic query aimed at
the function around it. search_code(..., kind="varlocal") reaches
them as well.
Legacy indexes with kind="variable" (pre-split) are detected and
included in results — reindex to fully benefit from the split.
Read-only. No side effects.
Args:
name: Variable name or prefix to search. Uses LIKE match
(e.g. g_ finds g_debug_level, g_state).
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.
kind: Optional kind filter — "varglobal", "varlocal",
"field", or None (all). Default None. The legacy
"variable" is also accepted, for an index made before the
kind was split.
limit: Maximum results (default 20, max 100).
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 of dicts, each with: name (str), qualified_name (str),
kind (str — "varglobal", "varlocal", "field", or
"variable" on an index made before the kind was split),
file (str),
line (int), signature (str — e.g. "const IPAddress modbus_ip"),
enclosing_function (str — function name for varlocal,
"<file scope>" for varglobal), enclosing_class (str — class
name for static members, empty otherwise),
references (list[dict] — function, file, line,
ref_kind).
No match gives ``[]``. One dict with ``error`` means the query
failed — check that key first.
A ``warning`` key marks a partial result.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind: 'varglobal', 'varlocal', 'field', or None for all. | |
| name | Yes | Variable name or prefix to search. Uses LIKE match (e.g. 'g_' finds g_debug_level, g_state). | |
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum results (default 20, max 100). | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |