List and search tools take a limit or cursor
Give list and search tools a "limit" with a sensible default and maximum plus a "cursor", and return a next cursor, so one call never floods the model’s context.
Check schema-pagination · Schema and description quality · default severity: advice · rubric 2.1.0
What fails
A list or search tool with no limit, page size or cursor can return more than fits in the model's context.
The rule
We suggest implementing some combination of pagination, range selection, filtering, and/or truncation with sensible default parameter values for any tool responses that could use up lots of context.
How to fix it
Add "limit" (with a default and a maximum) and "cursor" arguments, and return a next cursor.
- Add limit with a default (for example 20) and a maximum (for example 100).
- Add an optional cursor and return next_cursor when more results exist.
- Say in the description that results are paged.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'search_issues',
{
title: 'Search issues',
description: 'Search issues by text, 20 per page by default. Use when the user describes an issue but has no ID; pass next_cursor to get more.',
inputSchema: z.strictObject({
query: z.string().describe('Words to search for'),
limit: z.number().int().min(1).max(100).default(20).describe('Results per page, 1 to 100'),
cursor: z.string().optional().describe('next_cursor from the previous page'),
}),
outputSchema: z.object({
issue_ids: z.array(z.string()).describe('Matching issue IDs'),
next_cursor: z.string().describe('Cursor for the next page, empty when done'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ query, limit, cursor }) => {
const result = { issue_ids: [], next_cursor: '...' };
return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
},
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
from typing import TypedDict
server = MCPServer("issues")
class Result(TypedDict):
issue_ids: list[str]
next_cursor: str
@server.tool(
title="Search issues",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def search_issues(
query: Annotated[str, Field(description="Words to search for")],
limit: Annotated[int, Field(description="Results per page, 1 to 100", ge=1, le=100)] = 20,
cursor: Annotated[str | None, Field(description="next_cursor from the previous page")] = None,
) -> Result:
"""Search issues by text, 20 per page by default. Use when the user describes an issue but has no ID; pass next_cursor to get more."""
return {"issue_ids": [], "next_cursor": "..."}Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Is this the same as tools/list pagination?
No. tools/list pagination splits the list of tools; this is about the results one tool call returns.
What default limit should I use?
Small enough that a page fits comfortably in context: 20 to 50 items for typical records, fewer for large documents.
Related checks
- Search tools can return a concise answer
- Read tools declare an outputSchema
- The paste holds the whole tool list
- All checks in MCP tool input and output schemas
Further reading
How this check is graded
It counts toward: Schema and description quality. See the rubric.
Last verified against Anthropic: Writing effective tools for agents on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere