lsp-local-symbols

---
name: lsp-local-symbols
description: Fast file-scoped symbol analysis — find all usages of a symbol within the current file, list all symbols defined in the file, and get type info at a position. Use when you need local-scope analysis without a workspace-wide search.
argument-hint: "[symbol-name] in [file-path]"
user-invocable: true
allowed-tools: mcp__lsp__open_document mcp__lsp__list_symbols mcp__lsp__inspect_symbol mcp__lsp__get_document_highlights
license: MIT
compatibility: Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
metadata:
  required-capabilities: documentSymbolProvider
  optional-capabilities: documentHighlightProvider hoverProvider
---

> Requires the agent-lsp MCP server.

# lsp-local-symbols

File-scoped symbol analysis using the language server index. Faster than
workspace-wide search for questions about a single file: what symbols are
defined here, where is this symbol used within the file, and what type does it
have.

Read-only — does not modify any files.

## When to use

- "Where is `x` used in this file?" — use `get_document_highlights`
- "What functions and types are defined in this file?" — use `list_symbols`
- "What type does this symbol have?" — use `inspect_symbol`
- Reviewing a file before editing — get the full symbol map first
- Local refactor scoping — confirm a symbol is only used in one place before inlining it

Use `/lsp-impact` instead when you need workspace-wide callers and cross-file
references. Use `/lsp-dead-code` when auditing exported symbols for zero callers.

## When NOT to use

`get_document_highlights` is file-scoped by design — it only finds usages within
the open file. If a symbol is used across multiple files, this skill will not
find those. Use `find_references` (via `/lsp-impact`) for cross-file analysis.

---

## Workflow

### Step 1 — Open the file

Open the file so the language server tracks it:

```
mcp__lsp__open_document
  file_path: "/abs/path/to/file.go"
  language_id: "go"              # go, typescript, python, rust, etc.
```

### Step 2 — List all symbols in the file

Get the full symbol tree for the file:

```
mcp__lsp__list_symbols
  file_path: "/abs/path/to/file.go"
```

This returns all functions, types, variables, constants, and methods defined in
the file — including nested symbols (methods on types, fields in structs).

Use this to:
- Understand the file's structure before editing
- Find the exact position of a named symbol
- See what a file exposes before reading it in full

**Reading the output:** Each symbol has a `range` (full body including braces)
and a `selectionRange` (just the name). Coordinates are 1-based. Use
`selectionRange.start.line` and `selectionRange.start.character` as inputs to
`get_document_highlights` and `inspect_symbol`.

### Step 3 — Find all usages within the file

Call `get_document_highlights` at the symbol's position:

```
mcp__lsp__get_document_highlights
  file_path: "/abs/path/to/file.go"
  line: <selectionRange.start.line from Step 2>
  column: <selectionRange.start.character from Step 2>
```

Returns every occurrence of the symbol within the file, classified as:
- `read` — the symbol is read here
- `write` — the symbol is assigned/mutated here
- `text` — a text match (fallback when semantic classification isn't available)

**Speed note:** `get_document_highlights` is significantly faster than
`find_references` for file-local queries — it does not scan the entire workspace
index. Use it first; escalate to `find_references` only if you need cross-file
results.

### Step 4 — Get type information (optional)

For any position of interest, get the type signature and docs:

```
mcp__lsp__inspect_symbol
  file_path: "/abs/path/to/file.go"
  line: <line>
  column: <column>
```

Returns the hover text: type signature, documentation, and inferred types.
Useful for confirming what a symbol is before deciding to rename or inline it.

---

## Output format

Report results in three sections (omit any section with no content):

```
## Symbols in <filename>

### Functions / Methods
- `FuncName` — line N–M
- `(Type) MethodName` — line N–M

### Types
- `TypeName` (struct/interface/alias) — line N

### Variables / Constants
- `ConstName` = value — line N

---

## Usages of `<symbol>` in <filename>

N occurrences across M lines:
- line 12 [write] — assignment
- line 34 [read]  — passed as argument
- line 67 [read]  — returned

---

## Type info

`<symbol>`: <type signature from inspect_symbol>
```

---

## Decision guide

| Question | Tool |
|----------|------|
| What's in this file? | `list_symbols` |
| Where is X used in this file? | `get_document_highlights` |
| What type is X? | `inspect_symbol` |
| Is X safe to inline (used once)? | `get_document_highlights` — count occurrences |
| Is X used outside this file? | Use `/lsp-impact` instead |
| Is X dead code (no callers anywhere)? | Use `/lsp-dead-code` instead |

---

## Example

```
# "Where is the `config` variable used in server.go?"

open_document(file_path="/repo/server.go", language_id="go")
list_symbols(file_path="/repo/server.go")
  → finds `config` at selectionRange line 42, col 2

get_document_highlights(file_path="/repo/server.go", line=42, column=2)
  → returns 7 occurrences: 1 write (line 42), 6 reads

inspect_symbol(file_path="/repo/server.go", line=42, column=2)
  → "config *Config — the parsed server configuration"
```