Using the lsp tool
The lsp tool answers semantic questions through the language's own server:
it resolves through imports, types, and aliases, where grep only matches text.
Reach for it whenever the question is about a symbol; keep grep for plain
strings, comments, and file types no server supports.
Operations
| Operation |
Answers |
Needs |
definition |
where the symbol at a position is defined |
path, line, column |
references |
every place the symbol at a position is used |
path, line, column |
hover |
type signature + docs for the symbol at a position |
path, line, column |
documentSymbol |
the outline (types, functions, methods) of one file |
path |
diagnostics |
compiler/type errors and warnings for one file |
path |
Positions are 1-based, and column must point at the identifier (its first
character works). All paths resolve against the working directory.
Recipes
"Where is X defined?" — from any usage site of X:
{"operation": "definition", "path": "<file>", "line": <L>, "column": <C>}.
Don't know a usage site? Find one first (see next recipe's step 1).
"Everywhere X is used" — two steps, always:
- Locate the declaration:
rg -n --column '\bX\b' (the --column output is
exactly the coordinate the next call needs), or documentSymbol when you
already know the file.
{"operation": "references", "path": "<decl file>", "line": <L>, "column": <C>}.
A grep hit list is not a references answer: it includes comments and
strings, misses aliased imports, and can't distinguish same-named symbols.
Step 2 is what makes the answer authoritative.
"What is this / what's its signature?" — hover at the symbol. Prefer it
over reading the definition file when you only need the type or doc comment.
"What's in this file?" — documentSymbol before reading a large file; jump
straight to the line the outline gives you.
"Did my edit break anything here?" — diagnostics on the file after
editing. It reports the server's current analysis of the saved file.
Behavior worth knowing
- First query per workspace is slow (the server indexes — up to a minute
in a big repo). Later queries on that workspace are fast; don't give up
after one timeout, retry once.
- References are capped (default 100, header says how many exist).
- Unsupported file type or missing server returns advice text, not an
error — fall back to grep for that file. A missing server can be installed
with the user's consent via
lsp_enable (see the install-lsps skill for
toolchain prerequisites).
- Works inside dispatch subagents too (they share the parent's warm servers),
so symbol lookups are safe to fan out.
1---2name: lsp-guide3description: Recipes for the lsp tool — resolving where a symbol is defined, every place it is used, type signatures and docs, file outlines, and compiler/type errors through a real language server (Go, TypeScript/JavaScript, Python, Rust). Use when navigating or explaining code by symbol, finding callers or usages, checking what broke after an edit, or deciding between lsp and text search.4---56# Using the lsp tool78The `lsp` tool answers *semantic* questions through the language's own server:9it resolves through imports, types, and aliases, where grep only matches text.10Reach for it whenever the question is about a **symbol**; keep grep for plain11strings, comments, and file types no server supports.1213## Operations1415| Operation | Answers | Needs |16|---|---|---|17| `definition` | where the symbol at a position is defined | `path`, `line`, `column` |18| `references` | every place the symbol at a position is used | `path`, `line`, `column` |19| `hover` | type signature + docs for the symbol at a position | `path`, `line`, `column` |20| `documentSymbol` | the outline (types, functions, methods) of one file | `path` |21| `diagnostics` | compiler/type errors and warnings for one file | `path` |2223Positions are 1-based, and `column` must point **at the identifier** (its first24character works). All paths resolve against the working directory.2526## Recipes2728**"Where is X defined?"** — from any usage site of X:29`{"operation": "definition", "path": "<file>", "line": <L>, "column": <C>}`.30Don't know a usage site? Find one first (see next recipe's step 1).3132**"Everywhere X is used"** — two steps, always:33341. Locate the declaration: `rg -n --column '\bX\b'` (the `--column` output is35 exactly the coordinate the next call needs), or `documentSymbol` when you36 already know the file.372. `{"operation": "references", "path": "<decl file>", "line": <L>, "column": <C>}`.3839A grep hit list is **not** a references answer: it includes comments and40strings, misses aliased imports, and can't distinguish same-named symbols.41Step 2 is what makes the answer authoritative.4243**"What is this / what's its signature?"** — `hover` at the symbol. Prefer it44over reading the definition file when you only need the type or doc comment.4546**"What's in this file?"** — `documentSymbol` before reading a large file; jump47straight to the line the outline gives you.4849**"Did my edit break anything here?"** — `diagnostics` on the file after50editing. It reports the server's current analysis of the saved file.5152## Behavior worth knowing5354- **First query per workspace is slow** (the server indexes — up to a minute55 in a big repo). Later queries on that workspace are fast; don't give up56 after one timeout, retry once.57- **References are capped** (default 100, header says how many exist).58- **Unsupported file type or missing server** returns advice text, not an59 error — fall back to grep for that file. A missing server can be installed60 with the user's consent via `lsp_enable` (see the install-lsps skill for61 toolchain prerequisites).62- Works inside dispatch subagents too (they share the parent's warm servers),63 so symbol lookups are safe to fan out.
workweave