show_usage
Find semantic references to a symbol and inspect usage context.
Use show_usage to inspect callers, usage patterns, or the impact of changing a shared symbol.
Use when
- You need references to a visible source symbol or registered handle.
- You are assessing a rename, signature change, or other refactor.
Do not use when
- You need the symbol definition; use
jumporgrep_definition. - You need arbitrary text matches rather than semantic references.
Request
{"file":"/workspace/project/src/lib.rs","symbol_name":"UserService","line":42,"filter_params":{"include_paths":["src/**/*.rs"],"exclude_paths":["**/tests/**"],"limit":20},"workspace_root":"/workspace/project"}Parameters
| Field | Required | Default / bounds |
|---|---|---|
file | source form | Path; file_path is accepted as an alias. |
symbol_name | source form | Exact identifier at the requested line (symbol is an alias). |
line | source form | 1-based integer. |
handle | handle form | Registered handle; mutually exclusive with source fields. |
filter_params | no | Include/exclude globs and optional limit; excludes win. Omit limit for completeness. |
workspace_root | source form | Active workspace routing. |
What it returns
Semantic reference locations with containing context and parent-chain information. The total reference count comes from the language server and includes imports. Context Engine renders a reference only when its returned range belongs to a document symbol; import statements are not document symbols, so they count toward the total without appearing as usage contexts. Import-only files can be identified as probable re-exports.
Completeness depends on the configured language server index. If verified references are missing, wait 10 seconds and retry once.
Common mistakes
- Filtering or limiting a request intended as complete impact analysis.
- Passing a symbol name that is not present at the specified source line.
- Treating textual matches as semantic references.
Related tools
jump, grep_definition, hover, line_context