perf: tune Java LSP tool selection guidance

[wenytang-ms]

Summary

Tune the Java LSP language model tools (lsp_java_findSymbol, lsp_java_getFileStructure) based on 0.27.4 telemetry. Reduces wasted model turns from empty results and guessed paths, and clarifies tool routing.

Motivation (from 0.27.4 telemetry)

• findSymbol empty rate ~23%, dominated by workspaceSymbolNoMatch (1,424 calls / 415 users).
• getFileStructure error rate ~7.5%, dominated by fileNotFound (207 calls / 70 users) — mostly the model guessing paths.
• Tools look additive, not replacing discovery: ~68% of first Java LSP calls are immediately followed by another Java LSP call; top transitions are readFile → findSymbol → findSymbol (~18%) and tool_search → findSymbol → findSymbol (~9%). The model retries findSymbol itself instead of moving to getFileStructure / a precise readFile.

Changes

src/copilot/tools/javaContextTools.ts

• Server-side normalized retry for findSymbol: on a first miss, retry once with a normalized identifier (strip package qualifier com.foo.Bar→Bar, generics List<String>→List, and method parens foo()→foo). Moves the retry loop out of the model. Adds a retried telemetry field.
• Distinguish "indexing in progress" from "real no match" using languageServerApiManager.isFullyReady(): findSymbol reports indexingInProgress vs workspaceSymbolNoMatch; getFileStructure reports indexingInProgress vs documentSymbolProviderEmpty. The indexing case tells the model to retry shortly / fall back to grep.
• fileNotFound now returns an actionable hint ("call lsp_java_findSymbol to get the exact path; do not guess") instead of a dead end.

package.json — rewrote and tightened both tools' modelDescription:

• findSymbol: prefer over grep/file/semantic search; do not repeat on relevant results; tool retries internally, so on empty do not re-search (retry once only if it reports indexing, otherwise use generic search).
• getFileStructure: for known files only, do not guess paths, use findSymbol for workspace search, do not re-call the same file.
• Added userDescription and tags (UI / tool-picker only; not part of model context).

resources/skills/java-lsp-tools/SKILL.md and resources/instruments/javaLspContext.instructions.md — synced fallback guidance: findSymbol already retries internally, don't re-issue the same search; retry once only if indexing, otherwise fall back to grep; on fileNotFound, use findSymbol first.

Validation

• tsc -p . --noEmit passes; tslint passes; package.json is valid JSON.

Follow-up

• Re-run telemetry next release: check the indexingInProgress split and retried hit rate (Q3), and whether findSymbol → findSymbol chaining drops (Q9d).

[Copilot]

Pull request overview

This PR tunes the Java LSP Copilot tools’ behavior and guidance to reduce wasted model turns and improve routing based on telemetry (primarily by improving findSymbol miss handling, distinguishing indexing vs true empty results, and tightening “don’t guess paths” guidance).

Changes:

• Added a server-side one-time normalized retry for lsp_java_findSymbol (and telemetry field retried) to reduce repeated tool chaining on misses.
• Split “indexing in progress” from “no match / empty provider” for both findSymbol and getFileStructure, and improved fileNotFound responses with actionable hints.
• Updated tool guidance in package.json and synced skill/instrument docs to discourage repeated calls and path guessing.

Reviewed changes

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

File	Description
src/copilot/tools/javaContextTools.ts	Adds normalized retry, indexing-vs-empty distinction, improved payloads, and extra result fields/telemetry.
resources/skills/java-lsp-tools/SKILL.md	Updates guidance and fallback behavior for Java LSP tools.
resources/instruments/javaLspContext.instructions.md	Updates Java-file instructions for tool loading and fallback behavior.
package.json	Tightens modelDescription for tool picker routing; adds UI metadata (userDescription, tags).

---

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