find_variables
Locate C/C++ variables by full or partial name and trace which functions read or write them through the call graph, covering global, local, and field definitions.
Instructions
Find C/C++ variables by name or part of it 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 of the
functions that read or write the variable — the same ref_kind
values as find_references ("call", "ref", "member").
The list is capped at 30 per variable, and holds only references of
the selected build; references_total gives the whole count. Only
definitions are returned, globals first, then by name.
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 part of it. Substring match on name and
qualified name (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).
offset: Skip this many variables. Reads the next page; the page
notice names the offset to use.
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 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
or struct name for fields and static members, empty otherwise),
references (list[dict] — function, file, line,
ref_kind; at most 30), references_total (int — every
reference of the variable). When the list is cut,
references_hint names the find_references call that
lists them all.
The page notice ``{total, offset, shown, more, hint}`` comes
before the rows of the answer. ``total`` counts every variable that matches. When
``more`` is true, the ``hint`` names the call that reads the next
page. A page after the last variable gives one ``info`` dict that
names the total.
No match gives ``[]``. One dict with ``error`` means the query
failed — check that key first.
A ``warning`` dict that comes first means that indexed files
changed after the last index run: the results can be out of date.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind: 'varglobal', 'varlocal', 'field', legacy 'variable', or None for all. | |
| name | Yes | Variable name or part of it. Substring match on name and qualified name (e.g. 'g_' finds g_debug_level, g_state). | |
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| limit | No | Maximum results (default 20, max 100). | |
| offset | No | Skip this many variables. Reads the next page of a name that many variables share. | |
| 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 | 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 for you. 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 |