Agents drown during multi-hop graph tracing — RAG + search outperforms neighbors loops

[HumanBean17]

Problem

When agents use the MCP to trace call chains or follow flows through a large enterprise Java codebase, they consistently produce worse results than when they rely on RAG (search) + default code search tools alone. The neighbors loop — the core of the v2 GPS design — causes agents to:

1. Fan out exponentially — each CALLS hop produces 5-10 edges; after 3 hops the agent is lost in plumbing
2. Lack a visited set — LLMs revisit nodes, follow cycles, lose track of depth
3. Drown in low-signal edges — getters, log calls, framework plumbing dominate CALLS results
4. Consume context on traversal mechanics — reasoning about how to walk instead of what was found

RAG avoids this because vector search is query-directed (compresses through the lens of the question), while graph navigation is structure-directed (follows the code's actual topology, which is 80% plumbing).

Proposed tracks

Track 1: New /navigate-codebase skill (zero MCP changes)

A lighter alternative to /explore-codebase that encodes a RAG-first, graph-for-precision strategy:

• Use search to identify key nodes, then neighbors only to verify specific relationships
• Hypothesis-driven walking (form expectation before each hop)
• Aggressive NodeFilter usage on neighbors — never walk bare
• Depth discipline (2-3 hops max before reassessing)

Track 2: trace MCP tool proposal

The locked v2 design says "no trace tools — agent loops neighbors." But the agent can't do this well with available LLMs. A trace tool would be a batched navigation shortcut, not an answer engine — server-side multi-hop traversal that returns paths, not answers. The agent still interprets results.

Key design questions for the proposal:

• How to filter/rank edges server-side (role-based pruning, fan-out throttling)
• How to keep it GPS-aligned (returns structure, not answers)
• How it composes with the existing 4-tool surface

Track 3 (future): Service-tier metadata

Coarse-grained tagging of services as utility/business/infrastructure — low priority, helps at the margins but doesn't solve the core fan-out problem.

Scope

• Track 1 and Track 2 are independent and can proceed in parallel
• Track 1 is zero-risk (no code changes, skill only)
• Track 2 is a proposal only — implementation follows if the proposal is accepted