Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(mcp): present get_symbol as a follow-up rather than a place to start (#1427)
Raghav Chamadiya2f738ef0cdd0
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py b/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.pyindex 34ab06bd5..a270e54cc 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py@@ -30,7 +30,18 @@ from ._shared import _find_repo_root, emitting_buildfrom .bash_staleness import _read_in_flight_markerfrom .decision_inject import _session_decision_block-_CORE_TOOLS = "get_answer, get_context, get_symbol, search_codebase, get_risk"+#: The tools this block points a fresh session at. **Entry points only.**+#:+#: ``get_symbol`` used to be in this list and is deliberately not. It is a+#: follow-up on an id another response already handed over, and naming it here+#: — three times per session, in the one block every session reads first — is+#: what turns it into a first-reach tool. An agent that sees it listed beside+#: ``get_answer`` spends most of its retrieval calls fetching one symbol at a+#: time; an agent that does not, reaches for the coarse tools instead. The tool+#: is still served and still in the CLAUDE.md table, just not advertised as+#: somewhere to start. Same reasoning, at more length, in+#: ``generation/editor_files/tool_table.py``.+_CORE_TOOLS = "get_answer, get_context, search_codebase, get_risk"def _handle_claude_session_start(cwd: str, session_id: str = "") -> str | None:diff --git a/packages/core/src/repowise/core/generation/editor_files/tool_table.py b/packages/core/src/repowise/core/generation/editor_files/tool_table.pyindex 49c6242bf..222569976 100644--- a/packages/core/src/repowise/core/generation/editor_files/tool_table.py+++ b/packages/core/src/repowise/core/generation/editor_files/tool_table.py@@ -11,6 +11,23 @@ verified, continuation, directive, sources) stay named, because a row thatdrops them costs the agent a round trip to discover them. Reference detaillives in docs/agent/MCP_TOOLS.md, not here.+**A row is an advertisement, and a granular tool advertised as a peer gets+used granularly.** Where a short capability list named ``get_symbol`` beside+``get_answer``, agents spent the large majority of their retrieval calls on it+and finished having made *more* tool calls than an agent with no tools at all:+a per-symbol tool supplements navigation instead of replacing it, one symbol+per call. It is also the one tool whose payload cannot be trimmed — a trimmed+``get_symbol`` is 99% of a full one — so its calls are the ones no size work+can reach. Given the same surface with no such list, agents reached for+``get_answer`` instead and called ``get_symbol`` not at all.++So the ``get_symbol`` row leads by saying what it is NOT, and the+``get_answer`` and ``get_context`` rows say where bodies do come from. **This+is about naming, not about count**: harnesses that defer tool schemas read+this table and nothing else until they search, so serving fewer tools changes+nothing an agent sees. Do not "fix" it by shortening the row back to a neutral+capability description, and do not "fix" it by dropping the tool.+**Length is the constraint, not the feature list.** This table is resident inthe prompt prefix of every session in every repo repowise has indexed, so it isre-read on every API call: measured at 50.4x on one corpus, which makes a@@ -46,9 +63,9 @@ TOOL_TABLE_ROWS: dict[str, tuple[str, str]] = {),"get_symbol": ("get_symbol(id)",- "One verified body: `path.py::Name`, `path.py:140-180`, or `repowise#<hex>`. "- "Arrives in Read's numbered format; a `truncated` response carries a "- "`continuation`.",+ "**Follow-up, not an entry point** — one verified body for an id a prior "+ "response named (`path.py::Name`, `path.py:140-180`, `repowise#<hex>`). Never "+ "walk a file symbol by symbol; Read it.",),"search_codebase": ("search_codebase(query)",diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.pyindex f0a3b5a80..f636a99af 100644--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py@@ -662,30 +662,32 @@ async def get_symbol(query: str | None = None,id: str | None = None,) -> dict:- """Read one function/class/constant with live-verified line bounds.-- Raw source of one indexed symbol, bounded (~600 lines) — cheaper than- Read+offset math. ``source`` uses Read's exact line-numbered format;- treat it as an already-performed Read. ``verified: true`` = bounds- checked (or corrected) against the live file: no follow-up Read needed.- ``bounds: "approximate"`` = the symbol moved and re-location failed.- An ambiguous id (overloads, re-exports) returns ALL matching bodies in- ``candidates`` — none is silently chosen. Also serves live range reads- ("path.py:140-180", ≤200 lines, always verified) and omission refs- ("repowise#<12-hex>"). Index misses grep the live file and return- fallback_lines instead of a dead end. When ``truncated`` is true the+ """Follow-up read of one symbol whose id another response already gave you.++ **Not an entry point.** ``get_answer`` already ships ``symbol_bodies``, and+ for a whole file ``get_context(include=["skeleton"])`` or a plain Read is+ one call instead of many. Reach here for a body that was elided, or for a+ ``continuation`` / omission ref. Never walk a file symbol by symbol.++ Raw source of one indexed symbol, bounded (~600 lines). ``source`` uses+ Read's exact line-numbered format; treat it as an already-performed Read.+ ``verified: true`` = bounds checked (or corrected) against the live file:+ no follow-up Read needed. ``bounds: "approximate"`` = the symbol moved and+ re-location failed. An ambiguous id (overloads, re-exports) returns ALL+ matching bodies in ``candidates`` — none is silently chosen. Also serves+ live range reads ("path.py:140-180", ≤200 lines, always verified) and+ omission refs ("repowise#<12-hex>"). Index misses grep the live file and+ return fallback_lines instead of a dead end. When ``truncated`` is true theresponse carries a ``continuation`` token — the exact range read thatfetches the remainder; pass it straight back to get_symbol.Args:- symbol_id: "path/to/file.py::Name" (from get_context),- "path/to/file.py:140-180" for a live range, or an omission ref.+ symbol_id: "path/to/file.py::Name", "path/to/file.py:140-180" for a+ live range, or an omission ref.context_lines: extra lines before/after (0-50).repo: usually omitted.query: omission refs only — regex/substring filter on lines.- id: accepted alias for ``symbol_id`` — the tool table documents this- tool as ``get_symbol(id)``, so ``id=`` is the natural call and is- forgiven here rather than met with a hard argument error.+ id: accepted alias for ``symbol_id``."""if repo == "all":return _unsupported_repo_all("get_symbol")diff --git a/tests/unit/server/mcp/test_symbol_not_advertised.py b/tests/unit/server/mcp/test_symbol_not_advertised.pynew file mode 100644index 000000000..ed5ac8a92--- /dev/null+++ b/tests/unit/server/mcp/test_symbol_not_advertised.py@@ -0,0 +1,79 @@+"""``get_symbol`` is served, and is not advertised as somewhere to start.++Where a short capability list names ``get_symbol`` beside ``get_answer``, an+agent spends the large majority of its retrieval calls fetching one symbol at+a time, and ends up making more tool calls than an agent with no tools at all+— a per-symbol tool supplements navigation rather than replacing it. Given the+same surface with no such list, agents reach for ``get_answer`` instead.+``get_symbol`` is also the one tool whose payload cannot be trimmed, so its+calls are the ones no size work can reach.++So the lever is what the surfaces SAY, not what they serve, and these tests+pin the saying.++**Not a tool-count test, deliberately.** Harnesses that defer tool schemas+read the CLAUDE.md table and nothing else until they search, so serving fewer+tools changes nothing an agent sees. ``get_symbol`` must stay registered and+stay in the lean profile; the first test here is what stops a future reader of+this file from "fixing" the problem by removing the tool.+"""++from __future__ import annotations++from repowise.cli.commands.augment_cmd.session_start import _CORE_TOOLS+from repowise.core.generation.editor_files.tool_table import TOOL_TABLE_ROWS+from repowise.server.mcp_server._tool_selection import LEAN_TOOLS+++def test_get_symbol_is_still_served():+ assert "get_symbol" in LEAN_TOOLS+ assert "get_symbol" in TOOL_TABLE_ROWS+++def test_session_start_block_names_entry_points_only():+ """The one block every session reads first, before any tool description."""+ assert "get_symbol" not in _CORE_TOOLS+ for entry_point in ("get_answer", "get_context", "search_codebase"):+ assert entry_point in _CORE_TOOLS+++def test_the_tool_table_row_leads_with_what_get_symbol_is_not():+ """A row is an advertisement. This one has to read like a follow-up."""+ _signature, row = TOOL_TABLE_ROWS["get_symbol"]+ assert "not an entry point" in row.lower()+ # It still has to tell the agent how to call it successfully.+ assert "::" in row+++def test_the_coarse_rows_say_the_body_already_arrived():+ """Half the lever: the alternative has to be visible in the same table.++ Removing ``get_symbol``'s advertising without saying where bodies DO come+ from does not save anything; it just moves the agent to a Grep.+ """+ _sig, answer_row = TOOL_TABLE_ROWS["get_answer"]+ assert "symbol_bodies" in answer_row+ _sig, context_row = TOOL_TABLE_ROWS["get_context"]+ assert "skeleton" in context_row+++def test_get_symbol_schema_description_is_a_follow_up():+ """What Codex reads up front, and Claude Code reads after a ToolSearch."""+ from repowise.server.mcp_server.tool_symbol import get_symbol++ doc = (get_symbol.__doc__ or "").lower()+ assert "not an entry point" in doc+ assert "symbol by symbol" in doc+++def test_get_context_no_longer_points_per_symbol_at_get_symbol():+ """It used to say "symbol_ids to pipe into get_symbol (cheaper than Read)".++ That is the per-signature walk, recommended by the entry point itself, in+ a description shipped on every call.+ """+ from repowise.server.mcp_server.tool_context import get_context++ doc = get_context.__doc__ or ""+ assert "pipe into get_symbol" not in doc+ assert 'include=["skeleton"]' in doc