Add lsp_hover tool

[AJenbo]

This PR adds an lsp_hover tool to the agent, complementing the LSP tools added in #55744 (go_to_definition, find_references, rename_symbol, get_code_actions) with hover functionality that provides quick type lookups without needing to navigate to definitions.

Motivation

This has been requested independently by multiple users:

• #29724 — "Add tools to the assistant to let the AI introspect imports auto-complete and intellisense, make the LSP available to the agent panel"
• #35841 — "Include tools for interacting with active language servers"
• #47942 — "Allow LLMs access to LSPs"

The problem hover solves

The agent currently has no way to know what type a variable holds without reading class definitions, tracing inheritance chains, and guessing. For codebases where types come from magic methods, generics, or container resolution, this is especially fragile. A single lsp_hover call returns the type immediately.

Scenario	Without hover	With hover
"What type is $order->status?"	grep for definition → read model file → scan for property	One call returns the type
"What parameters does capturePayment() take?"	grep → find file → read_file → scan	One call returns full signature
"What are the cases of OrderStatus?"	grep (4 false positives) → read_file (143 lines)	One call returns all 8 cases with values
"What type is this magic property?"	Impossible — grep can't find it	Hover resolves it via the LSP

What it does

lsp_hover — Get type information, documentation, and deprecation notices for a symbol. Returns the same information you see when hovering in the editor: type signatures, docblocks, enum variants, parameter lists. Uses Project::hover() which routes to the appropriate LSP. The tool description positions it as a cheap "type oracle" for usage sites — try hover before grep. Includes guidance to avoid hovering on definition sites (where the LSP typically returns nothing useful) and encourages parallel batch hovering to build a complete type map of unfamiliar code.

The tool accepts (path, line, symbol) and optionally column for disambiguation when the same symbol appears multiple times on a line.

Implementation details

• Follows the same architecture as the existing LSP tools — same path resolution via find_project_path, same open_buffer pattern, same cancellation support.
• Uses Zed's existing LSP connections, so it automatically sees unsaved buffer state.
• Uses a dedicated symbol resolution module (lsp_tool_utils.rs) with richer position resolution than the existing symbol_locator:
  • Nearby line search (±4 lines) — agents often land on blank lines before code
  • Word boundary matching — prevents matching "Payment" inside "PaymentProcessor"
  • Case-insensitive fallback — handles agents using wrong casing
  • Fuzzy column disambiguation — when the same symbol appears multiple times on a line, an approximate column hint picks the nearest match
• Gated behind the same LspToolFeatureFlag as the other LSP tools.
• The grep tool description includes a nudge toward LSP tools for type/definition/reference lookups.

Testing

Tested against a real PHP monorepo with PHPantom LSP:

• Returns type signatures, enum cases with backing values, method signatures with all parameters, magic/virtual property types (things grep cannot find), and docblock content.
• Word boundaries prevent false matches — Payment doesn't match inside captureReservedPayment.
• Case-insensitive fallback correctly resolves PaymentToken to paymentToken.
• Fuzzy column correctly disambiguates token on lines with multiple occurrences.
• Nearby line search handles off-by-one line counting from the agent.
• The agent chains hover → definition → read_file naturally once the tool descriptions guide it.

Addresses #29724, #35841, #47942

Release Notes:

• Added lsp_hover tool to the agent, giving it direct access to language server hover information for type lookups, documentation, and signatures across any language with LSP support.

[cla-bot]

We require contributors to sign our Contributor License Agreement, and we don't have @AJenbo on file. You can sign our CLA at https://zed.dev/cla. Once you've signed, post a comment here that says '@cla-bot check'.

[AJenbo]

@cla-bot check

[cla-bot]

The cla-bot has been summoned, and re-checked this pull request!

[AJenbo]

For some added context I'm working on a new LSP for PHP. The LSP can print out a full project diagnostics in CLI mode, I usually feed it to the agent to diagnose issues, but the last 10% had the the agent pretty stumped, it kept failing to find the actual cause and going on unfruitful scavenger hunts. After implementing just these 3 basic tools it was able to identify the cause of nearly all the remaining issues in a single session. So while this may only be a minor improvement in general I think it can make a big difference for some edge cases where agents would previously struggle.

[morgankrey]

Some overlap with #55744 - ok to close this one?

[dlight]

#55744 was just merged, and there's a overlap (the find_references tool). But this PR has LSP hover, which enables agents to get type definition for any piece of code, which is really powerful, specially for code with heavy usage of generics.

(Agents can today retrieve type signatures of public APIs from documentation, but they can't easily get the type of a variable, specially after generics instantiation. For languages like Rust, Haskell or C++, that have libraries that do arbitrary type-level computation, this could make a lot of difference)

Maybe this could rebased on top of #55744's changes or something.

[AJenbo]

I'm happy to rebase this. In the future are there things I can do to get a review and merge in 5h like #55744 rather then being suggested for closing after 1 month :D

Update:
... [staff], right ok, that's not a simple thing I can just fix.

[AJenbo]

@dlight it's now rebased and only adds the LSP hover tool.

[AJenbo]

Fixed the CI stuff ... I think

[benbrandt]

Thanks for taking a look into this!
we're doing testing already on some LSP-based tools and want to see early results from those before committing to any more. Going to close for now (because I know these branches tend to be ripe for accruing conflicts) and we can revisit once we land some of the initial ones. Thanks!

[versecafe]

@benbrandt did the team ever do research into LSP diagnostic injections and language level rules for them to avoid hammering the model with 500 python lint errors for example while still making sure all TS type errors get through and on the timing of the injections, or has this not been explored yet?

[dlight]

@versecafe generally speaking, it's the LLM that is supposed to decide which tools they want to call, and when to make a call (tool calling is pull based, not push based). Zed can provide a tool for diagnostics or other LSP functions, but the model is in charge of selecting when they look at the LSP server. If the model is not behaving correctly, current best practice is to steer it through AGENTS.md, skills, and other prompting techniques.

There's a tradeoff here in that if you add too much tools, you will waste tokens of the context window with the description of each tool. The description of a tool is the thing the model uses to decide whether and when to call it, so you don't want to be so succinct as to make the tool seem irrelevant, but you don't want to describe too much as to waste your context window.

I'd expect that if anything, models might underuse lsp servers a lot, simply because it's less likely they are adequately trained for it.

[AJenbo]

I'd expect that if anything, models might underuse lsp servers a lot, simply because it's less likely they are adequately trained for it.

That's been my over all experience, they will often fall back to tried and true tools even when the LSP tools would have been more effective. But they do use them and it can really help with complicated cases where reading files isn't able to provide good info. But you can just tell them to rely more on it either via chat or AGENTS.md, which is probably good since each language's LSP option varies in usefulness.