show_usage

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 jump or grep_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	Only needed when multiple workspaces are active.

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.

Example

Real output, condensed — references to UpstreamClient, each shown inside its containing symbol:

13 references across 5 files

## context-engine-server/src/connector/runtime.rs (2 references)
- impl ConnectorRuntime { ... }
  - pub(crate) fn new( registration: RegisteredConnector, http_client: reqwest::Client, use_legacy_schema: bool, ) -> Self { ... } ["1000i00j" full 22L | code 21L | docs 1L]
    - 98|        let upstream/*: UpstreamClient*/ = UpstreamClient::new(

## context-engine-server/src/connector/tests/client.rs (3 references)
- fn test_client(address: SocketAddr) -> UpstreamClient { ... } ["1000j005" full 13L | code 13L]
  - 254|fn test_client(address: SocketAddr) -> UpstreamClient {

Every reference arrives inside the function that contains it, with the container's signature and an extract handle — the blast radius is assessed in the result itself, before any further reads.

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.

jump navigates to a definition instead of its references.
grep_definition locates a definition when no occurrence is known.
line_context expands an interesting reference location into its full container.
hover checks a signature before planning a change.