reticle_query answers “where is the thing I mean?” without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
Example
ref to act on and a source file to open, for 236 tokens.
Arguments
Every argument also has a predicate spelling, so
{ "role": "button" } works as shorthand for { "by": "role", "value": "button" }.
Use count_only when you only need a number
“Are there still three rows?” does not require three row descriptors:
total is not emitted on this path, because count already is the total.
A zero-match result tells you what is there
hint.route says where you actually are, presentTestids says what is on this page instead, and presentRegions distinguishes an empty list from a missing one. All of it without paying for a snapshot.
Reading the response
ref is the handle for every other tool: act, inspect, state. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
source appears when @reticlehq/react is installed. Note that both sidebar buttons above report Sidebar.tsx:41, and so do the three trimmed out of the example. That is the line where the component renders all five in a loop, which is exactly the line you want to edit.
truncated: true with total: 7 means limit cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
states distinguishes present from visible from enabled. An element can be all three and still be covered by a modal. reticle_inspect reports occluded for that.