# 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. Last verified against Anthropic: Writing effective tools for agents on 2026-11-18.

## 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.

Source: [Anthropic: Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)

## How to fix it

Add "limit" (with a default and a maximum) and "cursor" arguments, and return a next cursor.

1. Add limit with a default (for example 20) and a maximum (for example 100).
2. Add an optional cursor and return next_cursor when more results exist.
3. Say in the description that results are paged.

### TypeScript SDK

```ts
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

```python
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": "..."}
```

## 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](https://isokron.ai/mcp-check/checks/schema-response-format)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [The paste holds the whole tool list](https://isokron.ai/mcp-check/checks/spec-pagination-partial)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

## Further reading

- [Why MCP tool design matters for agent reliability](https://isokron.ai/research/why-mcp-tool-design-matters)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
