feat: reduce output noise in find_references and definitions_in_file

[BumpyClock]

Summary

After testing all 15 LSP-MCP tools for their value to LLM coding agents, find_references was identified as the noisiest tool, and definitions_in_file could benefit from additional filtering options.

Problem

find_references noise issues:

• 6 references = 6 overlapping context blocks - When include_code_context_lines is used, the output becomes extremely verbose
• Context blocks often overlap, creating redundant information
• No way to limit the number of results returned
• LLMs waste context window on repetitive code snippets

Example: A simple query for LspMcpServer references returned 6 references with 5-line context blocks each, many overlapping.

definitions_in_file opportunities:

• Currently returns full JSON for every symbol including ranges
• No way to get just a quick list of symbol names for scanning
• No filtering by symbol kind (e.g., only functions, only structs)

Proposed Changes

For find_references:

1. Add max_results: Option<u32> parameter (default 10)

   • Limits output to first N references
   • Prevents context window explosion on widely-used symbols

2. Change include_code_context_lines default to 0

   • Return just positions by default
   • Users explicitly opt-in to context when needed

3. Add compact: bool parameter

   • When true, returns simple ["path:line", "path:line", ...] format
   • Drastically reduces output size for navigation purposes

For definitions_in_file:

1. Add symbols_only: bool parameter

   • When true, returns just ["LspMcpServer", "new", "definitions_in_file", ...]
   • Quick scanning without full position data

2. Add kind_filter: Option<Vec<String>> parameter

   • Filter to specific symbol kinds: ["function", "struct"]
   • Reduces noise when looking for specific symbol types

Impact

• Reduced context usage for LLMs by 50-80% on reference queries
• Faster scanning of file structure with symbol-only mode
• More targeted queries with kind filtering

Related

Full tool analysis available in .ai_agents/tool_review.md