Java LSP Tools
Two compiler-accurate tools backed by the Java Language Server (jdtls). They return structured JSON that is easier to interpret than generic search results for Java symbol navigation.
Tools
lsp_java_findSymbol
Search for Java symbol definitions (classes, methods, fields) by name across the workspace. Supports partial matching.
- Input:
{ query, limit? } — limit defaults to 20, max 50
- Output:
{ results: [{ name, kind, container?, file, startLine, endLine, readFileInput, range }], total }; readFileInput is { filePath, offset, limit } for read_file, and file can be passed to lsp_java_getFileStructure
- Use instead of
grep_search, file_search, semantic_search, or search_subagent when looking for where a Java class/method/field is defined by identifier
- When source is needed for a returned symbol, use its
readFileInput directly
lsp_java_getFileStructure
Get hierarchical outline of a Java file (classes, methods, fields) with line ranges.
- Input:
{ uri, limit? } — workspace-relative path plus max outline items. Prefer file from lsp_java_findSymbol; limit defaults to 20, max 60. Must be a known path from prior tool results or user input — do not guess
- Output:
{ file, symbols: [{ name, kind, startLine, endLine, readFileRange, range, detail?, children? }], truncated? }; call read_file with filePath=file and the selected symbol's readFileRange
- Use before
read_file when you need to choose a precise line range in a known Java file
When to Use
| Task |
Use |
Not |
| Find class/method/field definition |
lsp_java_findSymbol |
grep_search |
| See known Java file outline before reading |
lsp_java_getFileStructure |
read_file full file |
| Search non-Java files (xml, gradle) |
grep_search |
lsp tools |
| Search string literals or comments |
grep_search |
lsp tools |
| Explore broad concepts without identifiers |
semantic_search or search_subagent |
lsp tools |
Typical Workflow
lsp_java_findSymbol → lsp_java_getFileStructure → read_file (specific lines only)
If lsp_java_findSymbol returns relevant symbols and source is needed, call read_file with the returned readFileInput, or call lsp_java_getFileStructure with the returned file when broader file context is needed.
Fallback
findSymbol returns empty → it already retried internally with a normalized identifier, so do not re-issue the same search. If the result says indexing is in progress, retry once after a short pause; otherwise fall back to grep_search- Path error (
fileNotFound) → use findSymbol to discover the correct path first; do not guess paths
- Tool error / jdtls not ready → fall back to
grep_search + read_file, don't retry more than once
Source: microsoft/vscode-java-dependency — distributed by TomeVault.
1---2name: java-lsp-tools3description: Compiler-accurate Java symbol navigation via the Java Language Server. Use lsp_java_findSymbol for Java identifiers and lsp_java_getFileStructure for known Java files; prefer them over generic search only for symbol/file-outline navigation. Use when this capability is needed.4---56# Java LSP Tools78Two compiler-accurate tools backed by the Java Language Server (jdtls). They return structured JSON that is easier to interpret than generic search results for Java symbol navigation.910## Tools1112### `lsp_java_findSymbol`13Search for Java symbol definitions (classes, methods, fields) by name across the workspace. Supports partial matching.14- Input: `{ query, limit? }` — limit defaults to 20, max 5015- Output: `{ results: [{ name, kind, container?, file, startLine, endLine, readFileInput, range }], total }`; `readFileInput` is `{ filePath, offset, limit }` for `read_file`, and `file` can be passed to `lsp_java_getFileStructure`16- **Use instead of** `grep_search`, `file_search`, `semantic_search`, or `search_subagent` when looking for where a Java class/method/field is defined by identifier17- When source is needed for a returned symbol, use its `readFileInput` directly1819### `lsp_java_getFileStructure`20Get hierarchical outline of a Java file (classes, methods, fields) with line ranges.21- Input: `{ uri, limit? }` — workspace-relative path plus max outline items. Prefer `file` from `lsp_java_findSymbol`; limit defaults to 20, max 60. Must be a known path from prior tool results or user input — do not guess22- Output: `{ file, symbols: [{ name, kind, startLine, endLine, readFileRange, range, detail?, children? }], truncated? }`; call `read_file` with `filePath=file` and the selected symbol's `readFileRange`23- **Use before** `read_file` when you need to choose a precise line range in a known Java file2425## When to Use2627| Task | Use | Not |28|---|---|---|29| Find class/method/field definition | `lsp_java_findSymbol` | `grep_search` |30| See known Java file outline before reading | `lsp_java_getFileStructure` | `read_file` full file |31| Search non-Java files (xml, gradle) | `grep_search` | lsp tools |32| Search string literals or comments | `grep_search` | lsp tools |33| Explore broad concepts without identifiers | `semantic_search` or `search_subagent` | lsp tools |3435## Typical Workflow3637**lsp_java_findSymbol → lsp_java_getFileStructure → read_file (specific lines only)**3839If `lsp_java_findSymbol` returns relevant symbols and source is needed, call `read_file` with the returned `readFileInput`, or call `lsp_java_getFileStructure` with the returned `file` when broader file context is needed.4041## Fallback4243- `findSymbol` returns empty → it already retried internally with a normalized identifier, so do not re-issue the same search. If the result says indexing is in progress, retry once after a short pause; otherwise fall back to `grep_search`44- Path error (`fileNotFound`) → use `findSymbol` to discover the correct path first; do not guess paths45- Tool error / jdtls not ready → fall back to `grep_search` + `read_file`, don't retry more than once4647---48> Source: [microsoft/vscode-java-dependency](https://github.com/microsoft/vscode-java-dependency) — distributed by [TomeVault](https://tomevault.io).49<!-- tomevault:4.0:skill_md:2026-06-20 -->
tomevault-io