diff --git a/package.json b/package.json index e479af16..765c32c7 100644 --- a/package.json +++ b/package.json @@ -52,8 +52,15 @@ { "name": "lsp_java_getFileStructure", "toolReferenceName": "javaFileStructure", - "modelDescription": "Get the outline (classes, methods, fields) of a Java file with symbol kinds and line ranges.\n\nUse before read_file to find specific line ranges. For searching across files, use lsp_java_findSymbol instead.\n\nOnly use file paths confirmed from prior tool results or user input. If unsure, call lsp_java_findSymbol first.", + "modelDescription": "Get the outline of a known Java file: classes, interfaces, methods, fields, symbol kinds, and line ranges.\n\nUse this after lsp_java_findSymbol returns a relevant file, or when the user already provided a Java file path. It helps choose a precise read_file range instead of reading the whole file.\n\nDo not use this for workspace-wide search. For Java class, method, or field lookup across files, use lsp_java_findSymbol first. Only pass file paths confirmed by the user or prior tool results; do not guess paths. Do not call this repeatedly for the same file unless the first result was empty or stale.", "displayName": "Java: Get File Structure", + "userDescription": "Get a Java file outline with classes, methods, fields, and line ranges.", + "tags": [ + "java", + "lsp", + "code-navigation", + "file-outline" + ], "canBeReferencedInPrompt": true, "icon": "$(symbol-class)", "when": "config.vscode-java-dependency.enableLspTools && javaLSReady", @@ -73,8 +80,15 @@ { "name": "lsp_java_findSymbol", "toolReferenceName": "javaFindSymbol", - "modelDescription": "Search for Java symbol definitions (classes, interfaces, methods, fields) across the entire workspace by name. Returns precise locations in ~60 tokens vs ~500+ tokens from grep_search.\n\nWhen to use:\n- To find where a class, method, or field is defined — faster and more precise than grep_search\n- To discover file paths before using other tools\n- Supports partial matching (e.g. 'UserSvc' finds 'UserServiceImpl')\n\nWhen NOT to use:\n- For non-Java files\n- To search for string literals, comments, or non-symbol text (use grep_search)", + "modelDescription": "Search Java symbols across the workspace by identifier and return concise definition locations.\n\nUse for precise Java class, interface, method, or field navigation. Prefer this over grep_search, file_search, semantic_search, or search subagents when the user is looking for a Java symbol by name or partial identifier.\n\nAfter this returns relevant symbols, do not call lsp_java_findSymbol again with the same or similar query. Continue with lsp_java_getFileStructure for the returned file, or read_file only the relevant line range.\n\nDo not use for non-Java files, string literals, comments, build files, XML, natural-language concepts, or broad codebase exploration. If there are no matches, retry at most once with a shorter materially different identifier, then fall back to generic search.", "displayName": "Java: Find Symbol", + "userDescription": "Find Java class, method, field, or interface definitions by name.", + "tags": [ + "java", + "lsp", + "code-navigation", + "symbol-search" + ], "canBeReferencedInPrompt": true, "icon": "$(search)", "when": "config.vscode-java-dependency.enableLspTools && javaLSReady", diff --git a/resources/instruments/javaLspContext.instructions.md b/resources/instruments/javaLspContext.instructions.md index 2c975a19..3cfd03fe 100644 --- a/resources/instruments/javaLspContext.instructions.md +++ b/resources/instruments/javaLspContext.instructions.md @@ -1,14 +1,15 @@ --- -description: REQUIRED for Java files. Provides compiler-accurate lsp_java_findSymbol and lsp_java_getFileStructure tools that replace grep_search, search_subagent, semantic_search, and file_search for Java symbol navigation. +description: Use Java LSP tools for precise Java symbol navigation. Prefer lsp_java_findSymbol and lsp_java_getFileStructure over generic search only when locating Java classes, methods, fields, or file outlines. applyTo: '**/*.java' --- -For Java files, two compiler-accurate `lsp_java_*` tools are available and return structured results in ~50 tokens vs ~500+ from generic search: +For Java symbol navigation, two compiler-accurate `lsp_java_*` tools are available and return structured results with smaller, easier-to-interpret payloads than generic search: - `lsp_java_findSymbol(query)` — find class/method/field definitions by name across the workspace - `lsp_java_getFileStructure(uri)` — get file outline (classes, methods, fields) with line ranges -These are deferred tools. Load them with `tool_search_tool_regex` using pattern `lsp_java_` before first use. +If these tools are not already available in the current tool list, load them with `tool_search` using a query such as `Java LSP symbol navigation lsp_java`. -Prefer these over `grep_search`, `search_subagent`, `semantic_search`, `file_search`, or full-file `read_file` when navigating Java symbols. Always use `findSymbol` to discover file paths before passing them to `getFileStructure` — do not guess paths. Fall back to `grep_search` if a tool returns empty or errors. +Use `lsp_java_findSymbol` before `grep_search`, `search_subagent`, `semantic_search`, or `file_search` only when the task is to locate Java symbols by name or partial identifier. If it returns relevant symbols, do not call it again with the same or similar query; next use `lsp_java_getFileStructure` for the returned file or `read_file` on the smallest useful line range. +Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. If `findSymbol` returns no matches, retry at most once with a shorter, materially different identifier before falling back to generic search. diff --git a/resources/skills/java-lsp-tools/SKILL.md b/resources/skills/java-lsp-tools/SKILL.md index 56a74cac..3895e37f 100644 --- a/resources/skills/java-lsp-tools/SKILL.md +++ b/resources/skills/java-lsp-tools/SKILL.md @@ -1,11 +1,11 @@ --- name: java-lsp-tools -description: Compiler-accurate Java code navigation via the Java Language Server. Use lsp_java_findSymbol to locate symbols and lsp_java_getFileStructure to inspect file outlines. Prefer over grep_search for Java symbol navigation. +description: 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. --- # Java LSP Tools -Two compiler-accurate tools backed by the Java Language Server (jdtls). They return structured JSON with fewer tokens than `grep_search` or `read_file`. +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 @@ -13,29 +13,33 @@ Two compiler-accurate tools backed by the Java Language Server (jdtls). They ret 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: `{ name, kind, location }` per result (~60 tokens) -- **Use instead of** `grep_search` when looking for where a class/method is defined +- **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 +- Do not repeat with the same or similar query after relevant results are returned ### `lsp_java_getFileStructure` Get hierarchical outline of a Java file (classes, methods, fields) with line ranges. - Input: `{ uri }` — workspace-relative path. Must be a known path from prior tool results or user input — do not guess - Output: symbol tree with `L start-end` ranges (~100 tokens) -- **Use instead of** `read_file` full scan when you need to understand a file's layout +- **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 file outline before reading | `lsp_java_getFileStructure` | `read_file` full file | +| 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 **findSymbol → getFileStructure → read_file (specific lines only)** +If `findSymbol` returns relevant symbols, move forward to `getFileStructure` or `read_file`; do not call `findSymbol` again with the same or similar identifier. + ## Fallback -- `findSymbol` returns empty → retry with shorter keyword, then fall back to `grep_search` +- `findSymbol` returns empty → retry at most once with a shorter, materially different identifier, then fall back to `grep_search` - Path error → use `findSymbol` to discover correct path first - Tool error / jdtls not ready → fall back to `grep_search` + `read_file`, don't retry more than once diff --git a/src/copilot/tools/javaContextTools.ts b/src/copilot/tools/javaContextTools.ts index 78969811..b985db5a 100644 --- a/src/copilot/tools/javaContextTools.ts +++ b/src/copilot/tools/javaContextTools.ts @@ -229,7 +229,9 @@ const findSymbolTool: vscode.LanguageModelTool = { const results = symbols.slice(0, limit).map(s => ({ name: s.name, kind: vscode.SymbolKind[s.kind], + container: s.containerName || undefined, location: `${vscode.workspace.asRelativePath(s.location.uri)}:${s.location.range.start.line + 1}`, + range: `L${s.location.range.start.line + 1}-${s.location.range.end.line + 1}`, })); resultCount = results.length; const findSymbolPayload = { results, total: symbols.length };