Improve Java LSP tool result handoff

Return structured file and line fields from findSymbol so the model can consume precise ranges without repeating symbol search. Accept line-suffixed Java locations in file structure resolution and document outlineInput handoff.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: wenytang-ms

package.json

@@ -52,7 +52,7 @@
       {
         "name": "lsp_java_getFileStructure",
         "toolReferenceName": "javaFileStructure",
-        "modelDescription": "Get a known Java file's outline: classes, interfaces, methods, fields, symbol kinds, and line ranges, to pick a precise read_file range instead of reading the whole file.\n\nUse after lsp_java_findSymbol returns a file, or when the user gave a Java file path; do not guess paths. Not for workspace-wide search\u2014use lsp_java_findSymbol for that. Do not re-call for the same file unless the first result was empty.",
+        "modelDescription": "Get a known Java file's outline: classes, interfaces, methods, fields, symbol kinds, and line ranges, to pick a precise read_file range instead of reading the whole file.\n\nUse after lsp_java_findSymbol returns outlineInput/file, or when the user gave a Java file path; do not guess paths. This accepts a workspace-relative Java path and tolerates a trailing line suffix such as src/Foo.java:42. Not for workspace-wide search\u2014use lsp_java_findSymbol for that. Do not re-call for the same file unless the first result was empty.",
         "displayName": "Java: Get File Structure",
         "userDescription": "Get a Java file outline with classes, methods, fields, and line ranges.",
         "tags": [
@@ -69,7 +69,7 @@
           "properties": {
             "uri": {
               "type": "string",
-              "description": "Workspace-relative path to a Java file. Must be a known path from prior tool results or user input — do not guess."
+              "description": "Workspace-relative path to a Java file. Prefer outlineInput or file returned by lsp_java_findSymbol. A trailing line suffix like src/Foo.java:42 is tolerated. Must be a known path from prior tool results or user input — do not guess."
             }
           },
           "required": [
@@ -80,7 +80,7 @@
       {
         "name": "lsp_java_findSymbol",
         "toolReferenceName": "javaFindSymbol",
-        "modelDescription": "Find Java class, interface, method, or field definitions across the workspace by name or partial identifier. Prefer over grep_search, file_search, semantic_search, or search subagents for Java symbol lookup.\n\nOn relevant results, do not repeat with a similar query; continue with lsp_java_getFileStructure or read_file on the returned line range. The tool retries internally, so on an empty result do not re-search\u2014retry once only if it reports indexing in progress, otherwise use generic search.\n\nDo not use for non-Java files, literals, comments, build/XML files, or conceptual exploration.",
+        "modelDescription": "Find Java class, interface, method, or field definitions across the workspace by name or partial identifier. Prefer over grep_search, file_search, semantic_search, or search subagents for Java symbol lookup.\n\nResults include file, startLine, endLine, range, and outlineInput. On relevant results, do not repeat with a similar query; use read_file on the returned file/range, or lsp_java_getFileStructure with outlineInput when broader file context is needed. The tool retries internally, so on an empty result do not re-search\u2014retry once only if it reports indexing in progress, otherwise use generic search.\n\nDo not use for non-Java files, literals, comments, build/XML files, or conceptual exploration.",
         "displayName": "Java: Find Symbol",
         "userDescription": "Find Java class, method, field, or interface definitions by name.",
         "tags": [

resources/instruments/javaLspContext.instructions.md

@@ -10,6 +10,6 @@ For Java symbol navigation, two compiler-accurate `lsp_java_*` tools are availab
 
 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`.
 
-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_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 `read_file` on the returned `file`/`range`, or call `lsp_java_getFileStructure` with `outlineInput` when broader file context is needed.
 
-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. `findSymbol` already retries internally with a normalized identifier, so do not re-issue the same search on an empty result: if it reports indexing in progress, retry once after a short pause; otherwise fall back to generic search.
+Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Prefer `outlineInput` or `file` from `findSymbol`; a trailing line suffix such as `src/Foo.java:42` is tolerated, but do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. `findSymbol` already retries internally with a normalized identifier, so do not re-issue the same search on an empty result: if it reports indexing in progress, retry once after a short pause; otherwise fall back to generic search.

resources/skills/java-lsp-tools/SKILL.md

@@ -12,13 +12,13 @@ Two compiler-accurate tools backed by the Java Language Server (jdtls). They ret
 ### `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?, location, range }], total }` (~60 tokens); `range` is `L start-end`
+- Output: `{ results: [{ name, kind, container?, file, startLine, endLine, location, range, outlineInput }], total, nextStep }`; `range` is `L start-end`, and `outlineInput` 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
 - 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
+- Input: `{ uri }` — workspace-relative path. Prefer `outlineInput` or `file` from `lsp_java_findSymbol`; a trailing line suffix such as `src/Foo.java:42` is tolerated. 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 before** `read_file` when you need to choose a precise line range in a known Java file
 
@@ -36,7 +36,7 @@ Get hierarchical outline of a Java file (classes, methods, fields) with line ran
 
 **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.
+If `findSymbol` returns relevant symbols, use `read_file` on the returned `file`/`range`, or call `getFileStructure` with `outlineInput` when broader file context is needed. Do not call `findSymbol` again with the same or similar identifier unless the returned symbols are irrelevant.
 
 ## Fallback
 

src/copilot/tools/javaContextTools.ts

@@ -79,14 +79,37 @@ function getToolErrorCode(error: unknown): string {
     return "unexpectedError";
 }
 
+function stripJavaLocationSuffix(input: string): string {
+    let normalized = input.trim();
+    if (normalized.length >= 2) {
+        const first = normalized[0];
+        const last = normalized[normalized.length - 1];
+        if ((first === "\"" && last === "\"") || (first === "'" && last === "'") || (first === "`" && last === "`")) {
+            normalized = normalized.substring(1, normalized.length - 1).trim();
+        }
+    }
+
+    const javaExt = ".java";
+    const javaIndex = normalized.toLowerCase().lastIndexOf(javaExt);
+    if (javaIndex < 0) {
+        return normalized;
+    }
+
+    const fileEnd = javaIndex + javaExt.length;
+    const suffix = normalized.substring(fileEnd);
+    return /^:L?\d+(?:[-:]\d+)?$/i.test(suffix) ? normalized.substring(0, fileEnd) : normalized;
+}
+
 /**
  * Resolve a file path to a vscode.Uri.
  * Accepts:
  *   - Full file URI:  "file:///home/user/project/src/Main.java"
  *   - Relative path:  "src/main/java/Main.java"
+ *   - Location string: "src/main/java/Main.java:42"
  *   - Absolute path:  "/home/user/project/src/Main.java" or "C:\\Users\\...\\Main.java"
  *
- * Relative paths are resolved against the first workspace folder.
+ * Relative paths are resolved against the first workspace folder unless they
+ * start with a workspace folder name in a multi-root workspace.
  * The resolved URI must use the file: scheme and fall under a workspace folder.
  */
 function resolveFileUri(input: string): vscode.Uri {
@@ -96,19 +119,31 @@ function resolveFileUri(input: string): vscode.Uri {
     }
 
     let uri: vscode.Uri;
+    const normalizedInput = stripJavaLocationSuffix(input);
 
-    if (input.includes("://")) {
+    if (normalizedInput.includes("://")) {
         // URI string (e.g. "file:///home/user/project/src/Main.java")
-        uri = vscode.Uri.parse(input);
+        uri = vscode.Uri.parse(normalizedInput);
         if (uri.scheme !== "file") {
             throw new Error(`Unsupported URI scheme "${uri.scheme}". Only file: URIs are allowed.`);
         }
-    } else if (path.isAbsolute(input)) {
+    } else if (path.isAbsolute(normalizedInput)) {
         // Absolute filesystem path (Unix or Windows)
-        uri = vscode.Uri.file(input);
+        uri = vscode.Uri.file(normalizedInput);
     } else {
-        // Relative path — resolve against first workspace folder
-        uri = vscode.Uri.joinPath(folders[0].uri, input);
+        // Relative path — resolve against a matching workspace folder when
+        // asRelativePath included the folder name, otherwise use the first root.
+        const normalizedRelativePath = normalizedInput.replace(/\\/g, "/");
+        const matchingFolder = folders.find(folder =>
+            normalizedRelativePath === folder.name || normalizedRelativePath.startsWith(`${folder.name}/`));
+        if (matchingFolder) {
+            const pathInFolder = normalizedRelativePath === matchingFolder.name
+                ? ""
+                : normalizedRelativePath.substring(matchingFolder.name.length + 1);
+            uri = vscode.Uri.joinPath(matchingFolder.uri, pathInFolder);
+        } else {
+            uri = vscode.Uri.joinPath(folders[0].uri, normalizedInput);
+        }
     }
 
     // Ensure the resolved path is under a workspace folder
@@ -288,15 +323,40 @@ const findSymbolTool: vscode.LanguageModelTool<FindSymbolInput> = {
                 return toResult(noMatchesPayload);
             }
             totalResults = symbols.length;
-            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}`,
-            }));
+            const results = symbols.slice(0, limit).map(s => {
+                const file = vscode.workspace.asRelativePath(s.location.uri);
+                const startLine = s.location.range.start.line + 1;
+                const endLine = s.location.range.end.line + 1;
+                return {
+                    name: s.name,
+                    kind: vscode.SymbolKind[s.kind],
+                    container: s.containerName || undefined,
+                    file,
+                    startLine,
+                    endLine,
+                    location: `${file}:${startLine}`,
+                    range: `L${startLine}-${endLine}`,
+                    outlineInput: file,
+                };
+            });
             resultCount = results.length;
-            const findSymbolPayload = { results, total: symbols.length };
+            const nextStep = symbols.length <= 3
+                ? [
+                    "These are exact Java symbol locations.",
+                    "Use read_file on the returned file/range, or lsp_java_getFileStructure with outlineInput for broader file context.",
+                    "Do not call lsp_java_findSymbol again for the same or similar symbol unless these results are irrelevant.",
+                ].join(" ")
+                : symbols.length > resultCount
+                    ? [
+                        "Many symbols matched.",
+                        "Refine only if the returned locations are not specific enough;",
+                        "otherwise use read_file on the relevant returned file/range.",
+                    ].join(" ")
+                    : [
+                        "Use read_file on the relevant returned file/range,",
+                        "or lsp_java_getFileStructure with outlineInput when file outline is needed.",
+                    ].join(" ");
+            const findSymbolPayload = { results, total: symbols.length, nextStep };
             responseCharCount = getResponseCharCount(findSymbolPayload);
             return toResult(findSymbolPayload);
         } catch (e) {