Using LSP Tools
Invariant Principles
- Semantic > Lexical: LSP understands scope, types, inheritance. Grep sees text.
- LSP for Symbols, Grep for Strings: Symbols = definitions, references, types. Strings = TODOs, comments, literals.
- Verify Before Fallback: Empty LSP result? Check file saved. Then try text-based.
- Atomic Operations Preferred:
rename_symbolhandles all files. Manual Edit misses references.
Reasoning Schema
Inputs
| Input | Required | Description |
|---|---|---|
filePath | Yes | Absolute path to file being analyzed |
line | Context | 1-indexed line number for position-based queries |
column | Context | 1-indexed column for position-based queries |
symbolName | Context | Fully-qualified name for definition/references |
language | No | Language identifier if ambiguous |
Outputs
| Output | Type | Description |
|---|---|---|
| Symbol locations | Inline | File paths and positions from navigation queries |
| Type information | Inline | Hover/signature data for understanding |
| Refactoring edits | Applied | Direct code modifications from rename/actions |
| Diagnostics | Inline | Errors and warnings for debugging |
Tool Priority Matrix
| Task | LSP Tool | Fallback |
|---|---|---|
| Find definition | definition | Grep func X|class X|def X |
| Find usages | references | Grep symbol name |
| Understand symbol | hover | Read + infer |
| Rename | rename_symbol | Multi-file Edit (risky) |
| File outline | document_symbols | Grep definitions |
| Callers | call_hierarchy incoming | Grep + analyze |
| Callees | call_hierarchy outgoing | Read function |
| Type hierarchy | type_hierarchy | Grep extends/implements |
| Workspace search | workspace_symbol_resolve | Glob + Grep |
| Refactorings | code_actions | Manual |
| Signature | signature_help | Hover or read |
| Diagnostics | diagnostics | Build command |
| Format | format_document | Formatter CLI |
| Edit by line | edit_file | Built-in Edit |
Parameters
Required: filePath (absolute), line/column (1-indexed), symbolName (fully-qualified for definition/references).
Decision Rules
Use LSP when:
- Finding true definition (not text match)
- Refactoring (rename, extract, inline)
- Understanding type relationships
- Finding semantic usages
- Cross-file navigation via imports
Use Grep/Glob when:
- Literal strings, comments, non-code text
- Regex patterns
- LSP returns empty but code exists
- Unsupported languages
- Non-symbols (TODOs, URLs, magic strings)
Workflows
Exploration: document_symbols (structure) -> hover (types) -> definition (jump) -> references (usage)
Refactoring: code_actions (discover) -> rename_symbol (execute) OR references (assess impact) -> manual
Type debugging: hover (inferred) -> type_hierarchy (inheritance) -> diagnostics (errors)
Call analysis: call_hierarchy incoming = "who calls?" | outgoing = "what calls?"
Anti-Patterns
Fallback Protocol
- LSP error/empty -> Check file saved (LSP reads disk)
- Try table fallback
- Persistent failure -> Feature unsupported by server
Self-Check
Before completing:
- Used semantic LSP tool for symbol-based queries (not text search)
- Verified file saved if LSP returned empty/unexpected results
- Applied atomic refactoring operations where available
- Documented fallback rationale if LSP bypassed
If ANY unchecked: STOP and reconsider approach.