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_symbol handles 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:
If ANY unchecked: STOP and reconsider approach.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: axiomantic-spellbook-using-lsp-tools3description: Using LSP Tools4---56# Using LSP Tools78<ROLE>9Language Tooling Expert. Reputation depends on leveraging semantic analysis over text matching for accurate, complete code navigation and refactoring.10</ROLE>1112## Invariant Principles13141. **Semantic > Lexical**: LSP understands scope, types, inheritance. Grep sees text.152. **LSP for Symbols, Grep for Strings**: Symbols = definitions, references, types. Strings = TODOs, comments, literals.163. **Verify Before Fallback**: Empty LSP result? Check file saved. Then try text-based.174. **Atomic Operations Preferred**: `rename_symbol` handles all files. Manual Edit misses references.1819## Reasoning Schema2021<analysis>22- Is target a symbol (function, class, variable) or literal text?23- Is LSP server active for this language?24- Does task need semantic understanding (types, scope, inheritance)?25</analysis>2627<reflection>28- Did LSP return expected results? If empty: file saved? Feature supported?29- Did fallback find matches LSP missed? Indicates LSP limitation vs. saved state.30</reflection>3132## Inputs3334| Input | Required | Description |35|-------|----------|-------------|36| `filePath` | Yes | Absolute path to file being analyzed |37| `line` | Context | 1-indexed line number for position-based queries |38| `column` | Context | 1-indexed column for position-based queries |39| `symbolName` | Context | Fully-qualified name for definition/references |40| `language` | No | Language identifier if ambiguous |4142## Outputs4344| Output | Type | Description |45|--------|------|-------------|46| Symbol locations | Inline | File paths and positions from navigation queries |47| Type information | Inline | Hover/signature data for understanding |48| Refactoring edits | Applied | Direct code modifications from rename/actions |49| Diagnostics | Inline | Errors and warnings for debugging |5051## Tool Priority Matrix5253| Task | LSP Tool | Fallback |54|------|----------|----------|55| Find definition | `definition` | Grep `func X\|class X\|def X` |56| Find usages | `references` | Grep symbol name |57| Understand symbol | `hover` | Read + infer |58| Rename | `rename_symbol` | Multi-file Edit (risky) |59| File outline | `document_symbols` | Grep definitions |60| Callers | `call_hierarchy` incoming | Grep + analyze |61| Callees | `call_hierarchy` outgoing | Read function |62| Type hierarchy | `type_hierarchy` | Grep extends/implements |63| Workspace search | `workspace_symbol_resolve` | Glob + Grep |64| Refactorings | `code_actions` | Manual |65| Signature | `signature_help` | Hover or read |66| Diagnostics | `diagnostics` | Build command |67| Format | `format_document` | Formatter CLI |68| Edit by line | `edit_file` | Built-in Edit |6970## Parameters7172Required: `filePath` (absolute), `line`/`column` (1-indexed), `symbolName` (fully-qualified for definition/references).7374## Decision Rules7576**Use LSP when:**77- Finding true definition (not text match)78- Refactoring (rename, extract, inline)79- Understanding type relationships80- Finding semantic usages81- Cross-file navigation via imports8283**Use Grep/Glob when:**84- Literal strings, comments, non-code text85- Regex patterns86- LSP returns empty but code exists87- Unsupported languages88- Non-symbols (TODOs, URLs, magic strings)8990## Workflows9192**Exploration:** `document_symbols` (structure) -> `hover` (types) -> `definition` (jump) -> `references` (usage)9394**Refactoring:** `code_actions` (discover) -> `rename_symbol` (execute) OR `references` (assess impact) -> manual9596**Type debugging:** `hover` (inferred) -> `type_hierarchy` (inheritance) -> `diagnostics` (errors)9798**Call analysis:** `call_hierarchy` incoming = "who calls?" | outgoing = "what calls?"99100## Anti-Patterns101102<FORBIDDEN>103- Using Grep for symbol rename (misses scoped references, hits false positives)104- Skipping LSP for "simple" refactors (simple becomes complex with inheritance)105- Trusting empty LSP results without checking file saved state106- Manual multi-file edits when `rename_symbol` available107- Ignoring `diagnostics` output when debugging type errors108</FORBIDDEN>109110## Fallback Protocol1111121. LSP error/empty -> Check file saved (LSP reads disk)1132. Try table fallback1143. Persistent failure -> Feature unsupported by server115116## Self-Check117118Before completing:119- [ ] Used semantic LSP tool for symbol-based queries (not text search)120- [ ] Verified file saved if LSP returned empty/unexpected results121- [ ] Applied atomic refactoring operations where available122- [ ] Documented fallback rationale if LSP bypassed123124If ANY unchecked: STOP and reconsider approach.125126---127> Converted and distributed by [TomeVault](https://tomevault.io/claim/axiomantic) — claim your Tome and manage your conversions.128<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io