MCP Tool Result Size Limit (25,000 tokens)

Claude and the MCP directory expect tool results to stay under about 25,000 tokens. Oversized results can cause errors or poor behavior. Below is how to stay under the limit.

How the server helps

The MCPServer plugin checks the size of each tool result before sending. If the JSON-encoded result is larger than the allowed size (see ResponseFormatter), the server returns an error instead of the payload and tells the client to use pagination or limit parameters. That prevents exceeding the limit at the transport level.

How to design tools so results stay small

1. Pagination

  • Add limit and offset (or page and pageSize) parameters to list/search tools.
  • Return only one page per call. Describe in the tool description: "Returns up to limit items starting at offset. Use pagination for large sets."
  • Example: getProjects(int $limit = 50, int $offset = 0).

2. Limit parameters

  • For tools that return lists, add a limit (or maxResults) parameter with a sensible default (e.g. 50 or 100).
  • Cap the maximum in code (e.g. min($limit, 200)) so a single call never returns more than a safe size.

3. Filtering

  • Let callers narrow results with filters (e.g. date range, status, search query) so they get fewer, relevant items instead of one huge dump.

4. Summaries instead of full data

  • Prefer returning summaries (id, name, key fields) in list tools.
  • Expose a separate detail tool (e.g. getProjectByID) for full data when the client needs one item.

5. Avoid huge blobs in the result

  • Do not return raw file contents or very long text unless the tool is specifically for “get one document.” For lists, return metadata and links, not full body.

Approximate size

  • ~25,000 tokens ≈ ~100,000 characters of JSON (rough rule of thumb: 1 token ≈ 4 characters).
  • The server uses a character-based threshold derived from this so results stay under the token limit.

Summary

Approach Use when
Pagination Lists that can be large
Limit/offset Same as above
Limit param Any tool returning a list
Filtering Search/list with many results
Summaries List tools; detail on demand

Design RPC methods with these in mind so tool results stay under the 25,000-token limit. The server-side check is a last line of defense; keeping responses small in your tools is the main prevention.