perf: improve Java LSP tool result handoff

[wenytang-ms]

Summary

This draft updates the Java LSP Copilot tool contract so successful symbol and file-outline results are easier to consume by downstream tools, especially VS Code Copilot's built-in read_file.

Recent telemetry analysis showed that raw findSymbol -> findSymbol is not a reliable problem metric by itself because most adjacent pairs are likely same-round/batch tool calls. The PR therefore avoids prescriptive next-step hints and focuses on factual, read-file-compatible result fields.

Changes

• lsp_java_findSymbol now returns structured location fields plus a direct read_file adapter:
  • file
  • startLine
  • endLine
  • range
  • readFileInput: { filePath, offset, limit }
• Removed the ambiguous location: path:line field from findSymbol; file is the canonical handoff field for lsp_java_getFileStructure.
• lsp_java_getFileStructure now returns a top-level file and per-symbol read ranges:
  • startLine
  • endLine
  • range
  • readFileRange: { offset, limit }
• Added limit to lsp_java_getFileStructure to control payload size:
  • default: 20
  • max: 60
  • returns truncated: true when capped
• Improved multi-root relative path handling when asRelativePath includes the workspace folder name.
• Updated LM tool metadata, skill docs, and Java chat instructions to describe the structured handoff.

Expected experiment signal

This PR is not expected to eliminate all findSymbol -> findSymbol transitions. Same-round/batch symbol lookups can still be valid.

Expected improvements:

• Higher findSymbol -> readFile when source is needed.
• Higher findSymbol -> readFile/getFileStructure within the next few tool calls.
• Lower delayed findSymbol -> findSymbol repeat rate, especially pairs with delta > 1s or delta > 5s.
• Lower generic search fallback after successful small findSymbol results.
• Smaller getFileStructure payloads while preserving getFileStructure -> readFile consumption.

Metrics that should not be treated as primary success criteria:

• Raw immediate findSymbol -> findSymbol, because it is inflated by batch/parallel tool calls.
• Forcing findSymbol to always be followed by read_file; lsp_java_getFileStructure, additional symbol lookup, or generic search can still be valid depending on the task.

Intentional non-goals

• No nextStep field in tool results; next-tool selection remains with the model.
• No outlineInput; file is the single path handoff field.
• No speculative path:line parsing in lsp_java_getFileStructure; findSymbol no longer returns a path:line field that would encourage this misuse.

Validation

• npm run compile
• npm run tslint
• npm test currently fails in existing Library Controller tests because toReferencedLibraryPath / toReferencedLibraryExcludePath are not exported from extension_bundle_1; unrelated to this LSP tool change.

[Copilot]

Pull request overview

This PR improves the Java LSP Copilot tools’ result “handoff” so downstream steps (e.g., read_file / lsp_java_getFileStructure) can consume lsp_java_findSymbol output more directly, and so file resolution is more tolerant of Java-style path:line inputs and multi-root workspaces.

Changes:

• Enhanced lsp_java_findSymbol payload with file, startLine, endLine, and outlineInput, and added a nextStep hint to reduce unnecessary repeat tool calls.
• Made file URI resolution tolerate Java location suffixes (e.g., src/Foo.java:42) and improved multi-root relative-path handling when the workspace folder name is included.
• Updated skill docs, instrument instructions, and tool metadata to prefer outlineInput/file handoff patterns.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/copilot/tools/javaContextTools.ts	Adds Java path:line tolerance, improves multi-root relative resolution, and enriches findSymbol results with additional fields and guidance.
resources/skills/java-lsp-tools/SKILL.md	Documents the updated findSymbol output fields and the preferred handoff flow using outlineInput/file.
resources/instruments/javaLspContext.instructions.md	Updates Java chat instructions to prefer read_file with file/range and getFileStructure with outlineInput.
package.json	Updates tool metadata/schema descriptions to reflect new fields and tolerated path:line inputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/copilot/tools/javaContextTools.ts:344

• The PR description says lsp_java_findSymbol will add an outlineInput field and a top-level nextStep hint, but the tool output here only includes file/startLine/endLine/readFileInput and returns { results, total }. If those fields are required for handoff, they should be included in the actual payload.

            const results = symbols.slice(0, limit).map(s => {
                const file = vscode.workspace.asRelativePath(s.location.uri);
                const { startLine, endLine } = toInclusiveLineRange(s.location.range);
                return {
                    name: s.name,
                    kind: vscode.SymbolKind[s.kind],
                    container: s.containerName || undefined,
                    file,
                    startLine,
                    endLine,
                    readFileInput: toReadFileInput(file, startLine, endLine),
                    location: `${file}:${startLine}`,
                    range: `L${startLine}-${endLine}`,
                };
            });
            resultCount = results.length;
            const findSymbolPayload = { results, total: symbols.length };
            responseCharCount = getResponseCharCount(findSymbolPayload);
            return toResult(findSymbolPayload);

[wenytang-ms]

Addressed in 467198e by removing the ambiguous location: file:line field from lsp_java_findSymbol; the intended lsp_java_getFileStructure handoff now uses the structured file field instead.

[wenytang-ms]

Addressed in 467198e by using the full lsp_java_getFileStructure tool name in the workflow example and guidance.