find_references
Finds a symbol's definition and all its call sites in a single query. Use for refactoring, impact analysis, rename planning, and dead-code detection.
Instructions
Atomic symbol definition + every usage in one call. Prefer this over the two-step Grep-based find-all-callers pattern (grep -rn X then filter to call sites by eye) and over chaining search_code(symbols=true) + search_code() — find_references returns both the definition and all call sites in a single call, complete with no follow-up searches needed.
Use this for: "find all callers of X" (the most common agent refactoring task); impact analysis before changing a function or class; rename planning; dead-code detection before deleting a function.
By default, matches inside string literals and comments are excluded (so test fixtures and doc comments don't drown out real call sites); pass include_strings: true to restore all occurrences. Returns {definition, references, total_references, pagination, status} where definition is the first symbol definition ({path, line, kind, symbol, span, preview}) or null, and references is a flat array of {path, line, preview} covering every textual occurrence including the definition site itself. Pagination applies to references only; if pagination.has_more is true, fetch the next page with offset. On "Index not found" / "stale" error, call index_project, then retry.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Include files matching glob patterns (e.g., ['src/**/*.rs']) | |
| kind | No | Filter definition lookup by symbol kind (function, class, struct, trait, etc.) | |
| lang | No | Filter by language (rust, typescript, python, go, etc.) | |
| mode | No | Response mode: "list" (default) returns full results with definition + references; "count" returns only {count, pattern} — faster, skips match body serialization. | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| limit | No | 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. | |
| offset | No | Pagination offset for references (skip first N). Use with limit. | |
| exclude | No | Exclude files matching glob patterns (e.g., ['target/**', 'tests/**']) | |
| pattern | Yes | Symbol name or text pattern to find references for (e.g., 'CacheManager', 'extract_symbols') | |
| include_strings | No | Include matches inside string literals and comments (default: false). By default these are excluded to focus on real call sites. |