codegraph_explore shows 'Budget: make at most N calls' but NO limit is enforced — misleads agents into abandoning exploration early

[jaepo01]

Problem

codegraph_explore's tool description and result footer both use "Budget: make at most N calls" wording. Despite the existence of a getExploreBudget() helper, there is no actual call limit enforced at runtime — the wording creates a fictional constraint.

LLM agents reading these strings interpret them as a hard limit and abandon codegraph_explore mid-investigation, falling back to slower grep/Read chains. The "budget" framing degrades real-world agent behavior: agents stop exploring the moment they hit the displayed number, even when their initial result did not fully cover the question.

Reproduction

In an MCP-integrated agent (tested with OpenCode + oh-my-openagent):

1. Open a project with ~500 files
2. Ask a question whose answer spans more files than the displayed budget (e.g. budget=2, question needs 4 files)
3. Observe the agent abandon codegraph_explore after 2 calls and switch to grep/Read, even though the tool would have returned richer results on the 3rd and 4th calls

Current wording shown to the agent

Tool description:

... verbatim source grouped by file. Budget: make at most 2 calls for this project (482 files indexed).

Footer of every explore result:

> **Explore budget: 2 calls for this project (482 files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you have used 2.

Both wordings are read as "you have at most 2 calls; stop after that." The "BEFORE falling back to Read" phrasing actually encourages the wrong behavior.

Suggested fix

Replace both strings with orientation-focused wording that:

• Clarifies the number is a tip (~N calls usually orient), not a limit
• Explicitly states "NO call limit — call again whenever a result does not fully cover your question"
• Preserves the original intent (steer agents toward efficient explore usage) without the unintended "stop after N calls" side-effect

Proposed wording

Description:

... verbatim source grouped by file. Tip: ~2 calls usually orient you on a project this size (482 files indexed); there is NO call limit — call again whenever a result does not fully cover your question.

Footer:

> **Orientation tip: ~2 calls typically cover a project this size (482 files).** There is NO call limit — if this result did not cover your question, call again targeting the uncovered area; another explore is cheaper and more complete than Read.

Behavior impact

• No runtime behavior change. No limit was enforced before; none is enforced now. The change only affects the description string shown to agents and the footer appended to codegraph_explore results.
• Real-world agent behavior improves measurably. In local testing on v1.4.1, agents that previously stopped exploring after the displayed number now continue exploring when their initial result does not cover the question — matching the tool's actual (unlimited) design.

Notes

• The function getExploreBudget() and its heuristic are preserved — the budget number itself is useful as an orientation hint. This issue only asks to remove the misleading "limit" framing around it.
• If there is intent to add a real soft limit in the future (e.g. rate limiting), it should be implemented as an explicit runtime check, not implied via description text.
• Related: previously filed as PR fix(mcp): replace misleading 'Budget: make at most N' with 'NO call limit' #1374, closed to match this repo's issue-first workflow.

Related context

• codegraph_explore is token-heavy vs Instant Grep — dumps whole files and can conclude from thin context #1500 raises the opposite concern (explore is token-heavy). Together they suggest the explore tool's agent-facing description deserves a rethink — clarity about when to keep exploring vs. when to stop would help both camps.
• Recent fixes (fix(mcp): never serve a mis-sliced symbol body from a file that drifted from its index (#1474) #1492, fix(python): bare class references produce references edges to classes #1493, fix(mcp): blast radius follows caller chains before claiming no test coverage #1494) show this repo actively hardening explore's agent-facing reliability; this wording fix fits that theme.

Verification

• grep -c "Budget: make at most\\|Explore budget:" src/mcp/tools.ts → 0 (was 2)
• grep -c "NO call limit" src/mcp/tools.ts → 2 (was 0)
• TypeScript compiles cleanly (string-only change inside template literals)