---
title: Why does an AI agent only see the first page of MCP results?
url: https://opencontroller.lyzr.com/blog/why-ai-agents-only-see-the-first-page-of-mcp-results
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# Why does an AI agent only see the first page of MCP results?

**Usually because nothing in the chain asks for page two. MCP defines cursor pagination only for list operations such as `tools/list`; the result of a tool call has no protocol-level paging. If the MCP server wraps an API that returns 25 items by default and does not expose a cursor or a "more results" signal, the agent treats those 25 as the whole answer.**

The symptom is subtle. An agent answers "which repositories use this library?" confidently and wrongly, because it saw one page of search results. Nothing errors. The fix sits in the MCP server design, the client and the evaluation suite.

## Where does pagination exist in MCP, and where does it not?

The MCP specification uses opaque, cursor-based pagination. The server decides page size, and clients must not assume a fixed size. A response includes an optional `nextCursor` when more results exist, and the client sends it back as `cursor` to continue.

| Layer | Paginated by the protocol? | Who must handle it |
|---|---|---|
| `tools/list` | Yes (`nextCursor`) | MCP client |
| `resources/list`, `resources/templates/list` | Yes | MCP client |
| `prompts/list` | Yes | MCP client |
| `tools/call` result content | No | MCP server author and the model |

Two failure modes follow. First, a client that ignores `nextCursor` on `tools/list` silently loses tools beyond page one, so the agent never knows they exist. Second, and more common, a tool such as `search_issues` returns the first page of an upstream API and says nothing about the rest.

The spec also says clients must treat cursors as opaque: an empty string is a valid cursor and must not be read as the end of results. Only a missing `nextCursor` means the list is finished.

## Why does the model not ask for more?

A model can only page if the tool gives it a way and a reason to. It needs three things in the tool definition and output:

1. An input parameter for the next page, such as `cursor` or `page`.
2. A clear signal in the result that more data exists, such as `has_more: true` with the cursor value.
3. Ideally a total count, so the model can judge whether paging through is worth it.

Without these, the result looks complete. Upstream APIs often default to small pages (25 or 30 items is common), and MCP servers that pass parameters straight through inherit that default.

## How should MCP tools that return lists be designed?

Use this checklist when building or reviewing an MCP server:

1. **Expose paging inputs.** Accept a cursor and a page size, with a sensible maximum.
2. **Return paging metadata.** Include `next_cursor`, `has_more` and, where the API provides it, `total_count`.
3. **Say it in the description.** State that results are paginated and how to request more. The description is what the model reads.
4. **Prefer filters to paging.** A tool that accepts precise filters (owner, date range, status) returns fewer, better results than one that forces the model to scan ten pages.
5. **Offer aggregate tools.** For "how many" questions, a `count_issues` tool beats paging through every item and costs far fewer tokens.
6. **Cap total work.** Limit how many pages one task may fetch, so a broad query cannot loop through thousands of records. See [how to stop an agent from looping](/blog/stop-an-ai-agent-from-looping).
7. **Handle invalid cursors.** The spec recommends error code -32602 (invalid params) for bad cursors on list operations; tools should return a clear error too.

Tool count matters here as well. Every extra parameter and description adds tokens to each request, a trade-off covered in [the token cost of MCP tool definitions](/blog/token-cost-of-mcp-tool-definitions).

## How do you test for truncated results?

Add pagination cases to your agent evaluations:

- Seed a test dataset with more items than one page and ask a question whose answer sits on page two.
- Ask counting questions where the true count exceeds the default page size.
- Check that the client retrieves the full `tools/list` from servers with many tools.
- Monitor production traces for tool results that hit exactly the page size, a strong hint that data was cut off. The broader pattern is in [monitoring MCP tool call failures](/blog/monitor-mcp-tool-call-failures).

A result that is exactly 25, 30 or 100 items long, followed by a confident summary, deserves a second look.

## Who owns the fix?

Pagination bugs fall between teams: the server author, the client or framework, and the agent owner. Your MCP server review should include paging as a standard check, alongside authentication and tool scope. The full review process is in the [guide to governing MCP servers](/blog/how-to-govern-mcp-servers).

## How Opencontroller does this

Opencontroller keeps a governed registry of agents, tools and MCP servers, so each server has an owner accountable for issues like this. Multi-turn evaluations can include questions whose answers sit beyond the first page, and LLM judges scoring production traffic can flag answers that are not grounded in complete tool results. Opencontroller Edge extends discovery to local MCP servers on developer devices. See the [capability reference](/capability-reference) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Does MCP paginate tool call results?**
No. The specification paginates list operations such as `tools/list`, `resources/list` and `prompts/list`. Paging inside a tool's result is up to the server's tool design.

**Who decides the page size in MCP list operations?**
The server. Clients must not assume a fixed page size and should keep requesting while a `nextCursor` is returned.

**How can I tell if my agent is missing results?**
Look for tool results that return exactly the default page size, and add evaluation cases where the correct answer is on page two.

## Key facts

- The MCP specification uses opaque cursor pagination (nextCursor in responses, cursor in requests) for list operations: tools/list, resources/list, resources/templates/list and prompts/list. The server sets page size; clients must not assume one.
- A missing nextCursor marks the end of results; an empty-string cursor is valid and must not be treated as the end. Invalid cursors should return error -32602.
- tools/call results are not paginated by the protocol, so MCP servers wrapping APIs with small default pages (often 25 or 30) can make agents treat a partial list as complete.
- Fixes: expose cursor and page-size inputs, return has_more, next_cursor and total_count, describe paging in the tool description, prefer filters and aggregate tools, cap pages per task, and add evaluation cases with answers beyond page one.
- Opencontroller by Lyzr keeps a governed registry of agents, tools and MCP servers, runs multi-turn evaluations and LLM judges on production traffic; Opencontroller Edge discovers local MCP servers.
- Opencontroller pricing starts from $250K per deployment per year.

## Related

- [How do you monitor MCP tool call failures across AI agents?](https://opencontroller.lyzr.com/blog/monitor-mcp-tool-call-failures.md)
- [How much do MCP tool definitions add to token costs?](https://opencontroller.lyzr.com/blog/token-cost-of-mcp-tool-definitions.md)
- [How many tools should one AI agent have?](https://opencontroller.lyzr.com/blog/how-many-tools-should-an-ai-agent-have.md)
- [More on Tools and MCP](https://opencontroller.lyzr.com/blog/cluster/tools-and-mcp)
