Bound every MCP response: short lists, paging and partial item reads #302
Description
Only memory_recall (maxChars), item_history (limit) and relation_list (depth, limit) let the caller size a response. The rest are fixed or unbounded:
task_listhas no limit (internally 300 root tasks) and returns every full description. On 2026-09-17 it returned 266,000 characters for this project, too large for an agent's tool output.item_searchreturns fixed 30 memories, 20 pages and 20 tasks without saying whether more exist.item_getalways returns the whole item; pages can hold 100,000 characters.
Principles
- Lists carry no details. A list returns what identifies, sorts and filters an entry;
item_getreturns the rest. - Lists page with one shared contract:
limitwith a small default,cursor, andtotalplushasMorein the response. Explained once in the system guide instead of on every tool. - Single items read in parts:
offsetandtakein characters with a high default, the server reporting where to continue. maxCharsstays where sections share one budget, which is recall only (#215).
Constraints
- The tool list is 20 characters under its budget in
McpDiscoveryTests(18,996 of 19,016). New parameters need shorter descriptions elsewhere or a deliberate, recorded raise of the budget. - Visibility: totals, cursors and outlines never reveal items or text the caller may not read.
Related: #219 (complete memory inventory, uses the list contract below), #215 (recall notices, done), #291/#295 (bag children page with the same contract).