fix(tools): bound every unbounded MCP response

[tirth8205]

Issue #849 reported one tool returning 247k tokens inside a workflow documented as "5 tool calls, 800 tokens total". PR #853 capped that one tool. Nobody had checked the other 29.

Eleven were unbounded, several on the default path, which is worse than #849: that one at least needed a large diff to trigger. These fire on a bare call with no arguments.

Independently verified, same graph before and after

Measured on a fresh full build of this repository (284 files, 5,764 nodes, 47,638 edges), serialized exactly as FastMCP does and counted with tiktoken cl100k_base:

tool, default arguments	before	after	cut
list_communities	339,235	12,045	96.5%
refactor dead_code	73,890	9,901	86.6%
refactor suggest	50,484	4,808	90.5%

A single default list_communities_tool call returned more tokens than most models can hold in context at all, against a documented budget of 800.

Worst-case paths were worse still: get_review_context 4.7M, get_surprising_connections 1.29M, get_hub_nodes 556k, get_community 536k, get_architecture_overview 625k.

Notable causes

• detect_changes was leaking get_affected_flows_tool has no detail_level or limit parameter and returns 247k+ tokens, breaking the documented token budget #849's exact payload through a second door: it embedded affected_flows with full steps lists, uncapped. Now metadata only, pointing at get_affected_flows_tool for detail.
• get_community returned 134k tokens even with include_members=False. The community's own members list was the payload.
• _extract_relevant_lines ignored max_lines_per_file when many functions in one file changed, because merged ranges covered the whole file.
• apply_refactor(dry_run=True) returned one unrestricted unified diff per touched file.
• PR Add detail_level and max_flows to get_affected_flows (fixes #849) #853's fix was half a fix: standard mode still carried a full steps list per flow at roughly 980 tokens each, so its 50-flow cap still produced about 49k, and max_flows=0 disabled the limit entirely. Its tests are updated here rather than worked around, because an escape hatch that returns a quarter of a million tokens is the bug get_affected_flows_tool has no detail_level or limit parameter and returns 247k+ tokens, breaking the documented token budget #849 reported.

Approach

Three shared helpers in tools/_common.py give every tool the contract #853 established: total always reports the untruncated count, truncated marks the cut, and the summary says "showing N of M". Validation matches query.py exactly, rejecting bools and values below 1 with the same message. Where a count alone cannot bound a response, a shared budget does: get_flow and get_affected_flows spend a step budget, get_review_context and detect_changes spend a source-line budget. Ceilings that depend on payload size vary by detail_level, mirroring how query.py caps minimal mode at five results.

Regression guard

tests/test_token_budget.py, 103 tests, offline, one shared fixture graph. It pins the contract three ways, because any one alone can be gamed:

1. Per-tool default and worst-case token budgets, recorded as data with arguments and reasoning inline.
2. test_hard_ceilings_bind asserts truncated list lengths equal the ceiling constants, so a cap that silently stops applying changes a length.
3. test_ceiling_constants_are_not_raised asserts the constants themselves, since a token budget can be masked by its own headroom.

Plus test_budget_table_covers_every_registered_tool, so a new @mcp.tool() cannot ship without a budget entry. Verified it fails on regression: raising _MAX_MEMBERS to 100000 produces 2 failures.

Four holes deliberately left open

tools/query.py was being modified concurrently by the uncertainty work (#884, #885), so these are reported rather than fixed here, each with a follow-up owed:

1. get_impact_radius, 3.4M tokens. changed_nodes and edges ignore max_results; only impacted_nodes is capped. Worse, max_results is not exposed on the MCP signature in main.py at all, so no client can bound it.
2. find_large_functions, 737k. limit neither validated nor capped.
3. traverse_graph, 385k. token_budget neither validated nor capped, and the check uses a len/4 heuristic applied after the entry is built.
4. semantic_search_nodes, 145k. limit neither validated nor capped.

The budget test asserts their default budgets and skips only their worst case, listing each in a QUERY_OWNED_UNBOUNDED set with the reason, so a regression in normal use is still caught.

Docs updated: LLM-OPTIMIZED-REFERENCE.md, docs/COMMANDS.md (new Result Bounds section; every signature there was stale, missing even #853's parameters) and docs/FEATURES.md.

Full suite 2872 passed, 9 skipped, 2 xpassed. ruff and mypy clean.

Relates to #849.

[github-actions]

code-review-graph review

Overall risk: 0.75 (HIGH) — 70 changed function(s)/class(es), 0 affected flow(s), 48 test gap(s)

Risk-scored changes

Risk	Level	Symbol	Location	Tested
0.75	high	code_review_graph/main.py::get_surprising_connections_tool	code_review_graph/main.py:949	no
0.75	high	code_review_graph/tools/analysis_tools.py::get_surprising_connections_func	code_review_graph/tools/analysis_tools.py:198	no
0.65	medium	code_review_graph/tools/analysis_tools.py::_project	code_review_graph/tools/analysis_tools.py:33	no
0.65	medium	code_review_graph/tools/community_tools.py::_cap_members	code_review_graph/tools/community_tools.py:30	no
0.65	medium	code_review_graph/tools/refactor_tools.py::_project	code_review_graph/tools/refactor_tools.py:37	no
0.65	medium	code_review_graph/tools/review.py::_project	code_review_graph/tools/review.py:63	no
0.60	medium	code_review_graph/tools/review.py::_extract_relevant_lines	code_review_graph/tools/review.py:316	no
0.55	medium	code_review_graph/main.py::detect_changes_tool	code_review_graph/main.py:677	no
0.55	medium	code_review_graph/tools/analysis_tools.py::get_hub_nodes_func	code_review_graph/tools/analysis_tools.py:38	no
0.55	medium	code_review_graph/tools/analysis_tools.py::get_bridge_nodes_func	code_review_graph/tools/analysis_tools.py:88	no

Test gaps

• code_review_graph/main.py::get_review_context_tool (code_review_graph/main.py:289)
• code_review_graph/main.py::get_flow_tool (code_review_graph/main.py:509)
• code_review_graph/main.py::get_affected_flows_tool (code_review_graph/main.py:543)
• code_review_graph/main.py::list_communities_tool (code_review_graph/main.py:575)
• code_review_graph/main.py::get_community_tool (code_review_graph/main.py:611)
• ...and 43 more without direct tests

Token savings: this graph-backed report used ~45,602 fewer tokens (~80%) than reading every changed file in full (estimated, chars/4 approximation).

---

Powered by code-review-graph — local-first analysis; no code leaves the CI runner.