Size responses for a context window, not a database dump

Return only what the agent needs for the task, in pages it can ask for, with sensible defaults, and say so when you cut something off and how to get the rest.

Why

Everything a tool returns lands in the agent's context window, which is limited and shared with the task, the conversation and every other tool result. A search that returns 5,000 rows or a record with every internal field can push out the information the agent actually needs, or simply be cut off by the client. Anthropic's guidance for tool builders is direct: implement some combination of pagination, range selection, filtering and truncation, with sensible defaults, for any response that could use up lots of context. Claude Code caps tool responses at 25,000 tokens by default, so a larger response does not reach the model whole unless the server sizes it. When you do truncate, Anthropic says to steer the agent with instructions, and it suggests a response_format parameter so the agent can ask for a concise or a detailed answer (in its example, 72 tokens against 206). MCP standardizes paging: the server picks the page size, returns a nextCursor when more results exist, and should keep cursors stable. OpenAI's app guidelines add what to leave out entirely: return only data relevant to the request and the tool's purpose, without diagnostic fields, trace or request IDs, or logging metadata unless the query needs them.

Do

Paginate and filter by default, offer a concise mode, and mark truncation with a hint on how to fetch more.

Don't

Return every row and every internal field, or truncate silently.

Artifact

{
  "results": [
    { "id": "ord_812", "customer": "Acme Ltd", "total": "129.00 EUR", "status": "shipped" }
  ],
  "nextCursor": "eyJwYWdlIjogMn0=",
  "truncated": true,
  "hint": "Showing 20 of 1,284 orders. Filter by status or date range, or pass nextCursor for the next page."
}

Tool input: { "query": "orders", "status": "shipped", "limit": 20, "response_format": "concise" }