Problem A — No tool documents its return format. pattern_search — is it grouped by file or per-line? search_code's compact vs snippet vs content — what does each look like? find_references depth=1 vs depth=2 — what changes?
Why this is a problem: AI agents must call tools blindly and infer the format from the output. This wastes tokens on trial calls and leads to incorrect parsing. For example, an agent might call search_code(query="x", output="compact") expecting file paths, but receives inline snippets and tries to parse them as file references — producing nonsensical follow-up actions.
Problem B — search_code vs pattern_search selection is unclear. Searching for HomeScene — which tool to use? The descriptions don't explain when to choose one over the other.
Why this is a problem: search_code uses semantic indexing and treats the query as natural language; passing TODO|FIXME as a regex OR expression returns garbage. Conversely, pattern_search treats the query as PCRE regex; passing a natural language phrase like "authentication flow" may match random lines. Agents frequently pick the wrong tool, get irrelevant results, and waste 2-3 round-trips correcting.
Problem C — find_references / impact_analysis can't disambiguate same-name symbols. Multiple handleClick functions in different files produce merged, unusable results.
Why this is a problem: In any project with common patterns (event handlers, utility functions, React hooks), same-name symbols are common. find_references(symbol="handleClick") returns references to ALL of them mixed together. The agent cannot tell which reference belongs to which definition, making the tool unreliable for refactoring analysis. get_symbol already has file_filter for disambiguation — the same should apply to reference/impact tools.
Proposed:
- Add brief return-format descriptions to each tool's description
- Add tool-selection guidance (e.g. "Use search_code for concept/identifier lookup. Use pattern_search for regex, OR expressions, or glob filtering.")
- Add file_filter to find_references and impact_analysis
Problem A — No tool documents its return format. pattern_search — is it grouped by file or per-line? search_code's compact vs snippet vs content — what does each look like? find_references depth=1 vs depth=2 — what changes?
Why this is a problem: AI agents must call tools blindly and infer the format from the output. This wastes tokens on trial calls and leads to incorrect parsing. For example, an agent might call search_code(query="x", output="compact") expecting file paths, but receives inline snippets and tries to parse them as file references — producing nonsensical follow-up actions.
Problem B — search_code vs pattern_search selection is unclear. Searching for HomeScene — which tool to use? The descriptions don't explain when to choose one over the other.
Why this is a problem: search_code uses semantic indexing and treats the query as natural language; passing TODO|FIXME as a regex OR expression returns garbage. Conversely, pattern_search treats the query as PCRE regex; passing a natural language phrase like "authentication flow" may match random lines. Agents frequently pick the wrong tool, get irrelevant results, and waste 2-3 round-trips correcting.
Problem C — find_references / impact_analysis can't disambiguate same-name symbols. Multiple handleClick functions in different files produce merged, unusable results.
Why this is a problem: In any project with common patterns (event handlers, utility functions, React hooks), same-name symbols are common. find_references(symbol="handleClick") returns references to ALL of them mixed together. The agent cannot tell which reference belongs to which definition, making the tool unreliable for refactoring analysis. get_symbol already has file_filter for disambiguation — the same should apply to reference/impact tools.
Proposed: