Feature: uniform caller-controlled output budgets (max_results/max_lines) + self-reported truncation on all tools

[eazene]

Feature request

Caller-controlled output budget parameters — max_results / max_lines / max_direct / max_transitive (or a single max_tokens) — accepted by every query tool, with truncation self-reported in the response (truncated: true, counts of what was dropped).

Why

For multi-agent use (orchestrators assembling task packets for worker agents), the caller knows its token budget; the server doesn't. Today budgets are only partially controllable (limit/offset on some tools; get_code_snippet caps at 500 lines) and not uniform.

Surveyed 10 comparable code-graph MCP servers: the two with the best agent ergonomics both do this — one exposes per-call max_results/max_lines/max_direct/max_transitive on nearly every tool; another hard-caps at 500 rows / 16k tokens and tells the model what was dropped. A silently truncated result is worse than a small one: the agent reasons confidently over the missing half.

Sketch

• Uniform optional max_rows + max_snippet_lines on all 15 tools (aliases fine).
• Responses always carry exact totals + truncated (much of this discipline already exists in trace_path/detect_changes — this is about making it uniform and caller-tunable downward).
• Bonus: a get_usage_stats-style per-session accounting tool (calls by name, chars returned) so operators can measure token savings.

[rayss868]

Adding a concrete use case for this: search_code currently caps enriched results at limit (default 10) and reports total_grep_matches/total_results so the caller can detect truncation — but with no offset parameter, the only ways to see the rest are to raise limit (re-running the whole search, which makes the response even bigger) or narrow the query via file_pattern/path_filter. For an agent driving this MCP, a truncated result that it cannot page through means either bloating context with a huge re-run, or reasoning over an incomplete result set it knows is truncated.

search_graph already has proper pagination (offset, has_more, total), so search_code is the odd one out. Making the truncation self-reported (truncated: true + what was dropped) and adding a way to fetch just the remainder (offset/paging or a stable cursor) across all query tools would fix exactly this: the agent re-checks only the missing slice instead of re-running everything.

For reference from the current source (v0.9.0, src/mcp/mcp.c):

• search_code schema: "There is no offset parameter; to see more, raise limit or narrow the query"
• search_graph schema: "has_more (true when total > offset+returned). Detect truncation with has_more, then page by re-calling with offset=offset+limit"