find_references
Locate a symbol's definition and all its usages across the codebase in one call. Simplify refactoring, impact analysis, and rename planning by seeing every reference at once.
Instructions
Find a symbol's definition AND all usage sites in a single call.
Purpose: Eliminates the two-step pattern of search_code(symbols=true) + search_code(). Returns both the definition and all usages atomically.
Returns: {definition, references, total_references, pagination, status}
Use this when:
"Find all callers of X" — the most common agent refactoring pattern
Code review: understand impact before changing a function or class
Rename planning: see every site that needs updating
Dead code detection: confirm nothing calls a function before removing it
definition: First matching symbol definition {path, line, kind, symbol, span, preview}, or null if no symbol definition exists for the pattern.
references: Flat array of {path, line, preview} — all textual occurrences including the definition site itself.
Pagination applies to references only. Use limit and offset. Check pagination.has_more for more pages.
Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exclude | No | Exclude files matching glob patterns (e.g., ['target/**', 'tests/**']) | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| 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.) | |
| limit | No | Max references per page (default: 100). Pagination applies to references only. | |
| offset | No | Pagination offset for references (skip first N). Use with limit. | |
| pattern | Yes | Symbol name or text pattern to find references for (e.g., 'CacheManager', 'extract_symbols') |