Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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_build
from .bash_staleness import _read_in_flight_marker
from .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.py
index 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 that
drops them costs the agent a round trip to discover them. Reference detail
lives 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 in
the prompt prefix of every session in every repo repowise has indexed, so it is
re-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.py
index 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 the
response carries a ``continuation`` token — the exact range read that
fetches 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.py
new file mode 100644
index 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