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:

1. 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.
2. {"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.