Skip to main content
Glama
reflex-search

Reflex

Official

find_references

Search code files for a symbol's definition and every usage in one call, filtering out strings/comments by default; count mode returns filtered totals.

Instructions

A symbol's definition and every usage in one call, in code files only; matches in strings and comments are left out (include_strings:true keeps them). Answer: {definition, references, total_references, returned_count, filtered_out, pagination}; mode:"count" returns the count after filtering.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fileNoOnly paths containing this substring
globNoOnly paths matching (gitignore rules)
kindNoSymbol kind of the definition
langNoLanguage filter: rust, python, typescript, text, …
modeNocount: {count, files} only
forceNoRun a pattern too broad to run by default
limitNoMax results (default 200, at most 500)
offsetNoSkip this many results (next page)
excludeNoSkip paths matching (gitignore rules)
patternYesText to find
containsNoSubstring match (grep -F) instead of whole identifiers
ignore_caseNoCase-insensitive (rg -i)
include_locksNoAlso search lock files
include_stringsNoKeep matches in strings and comments
include_generatedNoAlso search generated files

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changedv2.0.3
    • changedInput schema / properties / contains / description
      Previous value: -"Substring matching, like `grep -F`. DEFAULT IS FALSE, which matches WHOLE IDENTIFIERS ONLY: pattern \"verify_csrf\" does NOT match \"verify_csrf_form_field\", and \"jwks_rps\" does NOT match \"jwks_rps_limit\". Pass true to find a pattern anywhere inside a longer identifier. If a search returns 0, check the response `hint` — it reports how many substring matches exist."New value: +"Substring match (grep -F) instead of whole identifiers"
    • changedInput schema / properties / exclude / description
      Previous value: -"Exclude files matching glob patterns (e.g., ['target/**', 'tests/**']) Patterns follow gitignore rules: a pattern containing '/' (src/**/*.rs) is anchored at the index root; a bare name (*.rs, Makefile) matches at any depth; **/src/**/*.rs matches src/ anywhere; * does not cross /."New value: +"Skip paths matching (gitignore rules)"
    • addedInput schema / properties / file
      Added value: +{
      +  "description": "Only paths containing this substring",
      +  "type": "string"
      +}
    • changedInput schema / properties / force / description
      Previous value: -"Force execution of potentially expensive queries (bypasses broad query detection)"New value: +"Run a pattern too broad to run by default"
    • changedInput schema / properties / glob / description
      Previous value: -"Include files matching glob patterns (e.g., ['src/**/*.rs']) Patterns follow gitignore rules: a pattern containing '/' (src/**/*.rs) is anchored at the index root; a bare name (*.rs, Makefile) matches at any depth; **/src/**/*.rs matches src/ anywhere; * does not cross /."New value: +"Only paths matching (gitignore rules)"
    • changedInput schema / properties / ignore_case / description
      Previous value: -"Match letters regardless of case, like `rg -i` (`ignore_case` + `contains` is `rg -i -F`). Default false. The trigram index is still used, so this costs about the same as a case-sensitive search."New value: +"Case-insensitive (rg -i)"
    • addedInput schema / properties / include_generated
      Added value: +{
      +  "description": "Also search generated files",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / include_locks
      Added value: +{
      +  "description": "Also search lock files",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / include_strings / description
      Previous value: -"Include matches inside string literals and comments (default: false). By default these are excluded to focus on real call sites."New value: +"Keep matches in strings and comments"
    • changedInput schema / properties / kind / description
      Previous value: -"Filter definition lookup by symbol kind (function, class, struct, trait, etc.)"New value: +"Symbol kind of the definition"
    • changedInput schema / properties / lang / description
      Previous value: -"Filter by language (rust, typescript, python, go, etc.)"New value: +"Language filter: rust, python, typescript, text, …"
    • changedInput schema / properties / limit / description
      Previous value: -"Max references per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. Pagination applies to references only."New value: +"Max results (default 200, at most 500)"
    • changedInput schema / properties / mode / description
      Previous value: -"Response mode: \"list\" (default) returns full results with definition + references; \"count\" returns only {count, pattern}: every reference AFTER string/comment filtering (all pages, not one); with include_strings:true it is the raw total and equals list-mode total_references."New value: +"count: {count, files} only"
    • changedInput schema / properties / offset / description
      Previous value: -"Pagination offset for references (skip first N). Use with limit."New value: +"Skip this many results (next page)"
    • changedInput schema / properties / pattern / description
      Previous value: -"Symbol name or text pattern to find references for (e.g., 'CacheManager', 'extract_symbols')"New value: +"Text to find"
  2. Changed5 schema fields changedv2.0.1
    • addedInput schema / properties / contains
      Added value: +{
      +  "description": "Substring matching, like `grep -F`. DEFAULT IS FALSE, which matches WHOLE IDENTIFIERS ONLY: pattern \"verify_csrf\" does NOT match \"verify_csrf_form_field\", and \"jwks_rps\" does NOT match \"jwks_rps_limit\". Pass true to find a pattern anywhere inside a longer identifier. If a search returns 0, check the response `hint` — it reports how many substring matches exist.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / exclude / description
      Previous value: -"Exclude files matching glob patterns (e.g., ['target/**', 'tests/**'])"New value: +"Exclude files matching glob patterns (e.g., ['target/**', 'tests/**']) Patterns follow gitignore rules: a pattern containing '/' (src/**/*.rs) is anchored at the index root; a bare name (*.rs, Makefile) matches at any depth; **/src/**/*.rs matches src/ anywhere; * does not cross /."
    • changedInput schema / properties / glob / description
      Previous value: -"Include files matching glob patterns (e.g., ['src/**/*.rs'])"New value: +"Include files matching glob patterns (e.g., ['src/**/*.rs']) Patterns follow gitignore rules: a pattern containing '/' (src/**/*.rs) is anchored at the index root; a bare name (*.rs, Makefile) matches at any depth; **/src/**/*.rs matches src/ anywhere; * does not cross /."
    • addedInput schema / properties / ignore_case
      Added value: +{
      +  "description": "Match letters regardless of case, like `rg -i` (`ignore_case` + `contains` is `rg -i -F`). Default false. The trigram index is still used, so this costs about the same as a case-sensitive search.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / mode / description
      Previous value: -"Response mode: \"list\" (default) returns full results with definition + references; \"count\" returns only {count, pattern} — faster, skips match body serialization."New value: +"Response mode: \"list\" (default) returns full results with definition + references; \"count\" returns only {count, pattern}: every reference AFTER string/comment filtering (all pages, not one); with include_strings:true it is the raw total and equals list-mode total_references."
  3. Changed3 schema fields changedv1.6.0
    • addedInput schema / properties / include_strings
      Added value: +{
      +  "description": "Include matches inside string literals and comments (default: false). By default these are excluded to focus on real call sites.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Max references per page (default: 100). Pagination applies to references only."New value: +"Max references per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. Pagination applies to references only."
    • addedInput schema / properties / mode
      Added value: +{
      +  "description": "Response mode: \"list\" (default) returns full results with definition + references; \"count\" returns only {count, pattern} — faster, skips match body serialization.",
      +  "enum": [
      +    "list",
      +    "count"
      +  ],
      +  "type": "string"
      +}
  4. First observedv1.0.0

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does meaningful work: it discloses that only code files are searched, that string/comment matches are filtered by default, and it exposes filtered_out plus pagination fields. It omits any mention of the 'force' safeguard for overly broad patterns, which is a notable behavioral gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The behavior and scope come first, followed by the return shape, so it is well front-loaded. It is dense and reads as a run-on, but nearly every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the answer fields (definition, references, total_references, returned_count, filtered_out, pagination). For a 15-parameter read tool with fully documented schema, the only real gap is the undocumented 'force' safeguard.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 15 parameters, including include_strings and mode. The description restates those two behaviors (include_strings keeps string/comment matches; mode:'count' returns counts after filtering) without adding syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('a symbol's definition and every usage in one call') and scopes it ('in code files only'), which clearly separates it from a generic grep-style sibling like search_code or search_regex. It stops short of naming which sibling to use instead, so it earns a 4 rather than a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the default filtering behavior (strings/comments excluded, include_strings overrides) and the count-mode variant, but there is no explicit when-to-use-this-vs-siblings guidance or statement of prerequisites. Adequate but leaves the routing decision to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.