Summary
MCP tool responses for search, definition, and references (McpToolHandlers.cs:300-314, 390-408, 461-481) return a results array without any truncated boolean or total count. An agent that receives 20 results cannot tell whether the query produced exactly 20 hits, or 20 out of 980 hits silently clamped by the server-side limit. The result: the agent either over-trusts a clamped list or wastes turns paginating by guessing larger limit values that may or may not have been honoured.
Where
src/CodeIndex/Mcp/McpToolHandlers.cs:300-314 (search response)src/CodeIndex/Mcp/McpToolHandlers.cs:390-408 (definition response)src/CodeIndex/Mcp/McpToolHandlers.cs:461-481 (references response)
Suggested approach
(1) Extend every MCP tool result envelope with truncated: bool (true if the server stopped at the configured ceiling) and total: int|null (null when computing total would be too expensive, otherwise the true count). (2) When the underlying SQL query is naturally cardinality-bounded (e.g. references for one symbol), compute and return the true total. (3) For full-text search where computing total is expensive, run an inexpensive COUNT(*) only when truncated=true and the result count equals the requested limit. (4) Mirror the same envelope on CLI --json output so scripts get the same signal. (5) Document the envelope under "MCP response envelope" and reference it from each tool's description. (6) Add regression tests that assert truncated=true and a sensible total when results exceed the limit, and truncated=false otherwise. (7) Cross-link with #1616 (batch_query partial completion) and #1472 (pagination cursors).
Summary
MCP tool responses for
search,definition, andreferences(McpToolHandlers.cs:300-314, 390-408, 461-481) return aresultsarray without anytruncatedboolean ortotalcount. An agent that receives 20 results cannot tell whether the query produced exactly 20 hits, or 20 out of 980 hits silently clamped by the server-side limit. The result: the agent either over-trusts a clamped list or wastes turns paginating by guessing largerlimitvalues that may or may not have been honoured.Where
src/CodeIndex/Mcp/McpToolHandlers.cs:300-314(search response)src/CodeIndex/Mcp/McpToolHandlers.cs:390-408(definition response)src/CodeIndex/Mcp/McpToolHandlers.cs:461-481(references response)Suggested approach
(1) Extend every MCP tool result envelope with
truncated: bool(true if the server stopped at the configured ceiling) andtotal: int|null(nullwhen computing total would be too expensive, otherwise the true count). (2) When the underlying SQL query is naturally cardinality-bounded (e.g.referencesfor one symbol), compute and return the truetotal. (3) For full-text search where computing total is expensive, run an inexpensiveCOUNT(*)only whentruncated=trueand the result count equals the requested limit. (4) Mirror the same envelope on CLI--jsonoutput so scripts get the same signal. (5) Document the envelope under "MCP response envelope" and reference it from each tool's description. (6) Add regression tests that asserttruncated=trueand a sensibletotalwhen results exceed the limit, andtruncated=falseotherwise. (7) Cross-link with #1616 (batch_query partial completion) and #1472 (pagination cursors).