AI agent tool output limits: paginate, summarize, or return a file
AI agent tool output limits decide what happens when a tool returns far more data than the next model turn can use. The practical answer is rarely “send everything.” Return a small page for selection, a structured summary for reasoning, or a file reference for material that must remain complete. That protects context, cost, and the agent’s ability to finish the actual task.
Large results show up quickly in production: a full audit log, an HTML error page from a proxy, or a generated report with embedded data. Pushing that payload straight into the model can crowd out the user’s request before the agent has made a decision.
Contents
- Why AI agent tool output limits differ from token limits
- Choose an output shape before building the tool
- Use a four-part response contract
- Apply the boundary in OpenClaw
- Test the limit as a normal failure mode
- FAQ
Why AI agent tool output limits are different from token limits
A model’s maximum output tokens control what the model writes. Tool output limits control what enters the model after the tool has already run. They solve different problems.
| Limit | Protects | Typical failure when missing |
|---|---|---|
| Model output token cap | The generated assistant reply | A long but incomplete answer |
| Tool result size cap | Model context and runtime memory | A huge API response displaces the task or exhausts memory |
| Page size and cursor | Retrieval precision | The agent receives an unsearchable dump |
| File handoff | Fidelity for large artifacts | Important source material is silently truncated |
The distinction matters for MCP tools. The MCP discussion on response-size limits describes a familiar failure: a server returns a large dataset, the client forwards it into context, and the agent spends tokens and context budget before it can decide what to do with the data.
OpenClaw’s v2026.7.1 release notes group oversized-response failures with Gateway and provider reliability work. That is the right framing. A size boundary is a reliability control, not a cosmetic formatting preference.
Choose the right output shape before a tool is built
A useful tool contract starts with the next decision the agent must make. Do not expose an API’s raw “list all” response just because the API offers it.
Paginate when the agent needs to choose
Pagination is the default for lists: messages, issues, users, transactions, files, search results, or audit events. Return a stable page, a cursor, the total count when it is cheap to obtain, and enough fields for selection. Ask for the next page only after the agent has a reason to inspect it.
For example, a search_customers tool should return customer ID, name, status, and a small result page. It should not return every address, event, note, and invoice for every possible match. A second get_customer tool can fetch the detail after the agent selects an ID.
This also makes the model more reliable. A narrow page gives it a clear choice. A 5,000-row JSON blob invites it to miss the relevant record or invent a conclusion from a partial read.
Summarize when the agent needs a conclusion
Use a summary when the next step is analysis rather than selection. The tool can compute counts, ranges, top categories, anomalies, and a bounded sample. Include the method in the response so the model knows what the summary omits.
A security-events tool, for instance, can return the number of failed logins by source, the most recent timestamps, a list of affected accounts capped to a small sample, and a cursor for the raw events. That is enough to decide whether to investigate. It is not enough to reconstruct the full incident, which is exactly why the raw path still needs to exist.
MLflow’s tool-use guidance makes the broader point: validate tool outputs before they reach the agent, and keep tools narrow and job specific. Output shaping is part of that validation.
Return a file or handle when completeness matters
Some results must remain whole: a generated CSV, a long research corpus, a PDF, a video transcript, or a trace bundle. Do not paste them into a chat turn and hope the context window is kind.
Return a durable reference instead: a file path inside the approved workspace, a download handle, an object ID, or a safe URL with its access rules. Then give the agent a separate tool for reading a bounded slice, searching within the artifact, or requesting a summary.
That pattern keeps a useful separation between storage and context. The model can ask for lines 400 through 480, search for a customer ID, or inspect the headings first. It does not need the entire artifact to decide its next action.
A four-part response contract for tools
The following contract works for MCP servers, internal plugins, and API wrappers. It is deliberately boring. That is a strength.
- State the result kind. Return
page,summary,artifact, orerrorrather than an ambiguous text blob. - Set an explicit bound. Cap page length, sample count, bytes read, and error-body capture. Report that a cap applied instead of silently pretending the result was complete.
- Keep a continuation path. Supply a cursor, artifact reference, search query, or detail endpoint. A bounded result without a way forward makes the agent guess.
- Preserve machine-readable fields. Include stable IDs, counts, and a short schema. Do not force the model to parse a prose explanation just to request the next page.
Here is a compact shape for a large list result:
{
"kind": "page",
"items": [{"id": "evt_1042", "time": "2026-08-23T01:05:00Z", "type": "auth_failure"}],
"returned": 1,
"total": 1842,
"next_cursor": "opaque-cursor",
"truncated": true
}The word truncated is not an error by itself. It tells the agent that it has a partial view and should use the continuation path before making a claim about the complete set.
Where OpenClaw fits in the boundary
OpenClaw sits between messaging channels, models, browser and file tools, plugins, and long-lived sessions. That makes output boundaries operationally important. A response that is too large can affect more than one model call; it can delay a channel reply, consume Gateway memory, or make a later session harder to inspect.
The OpenClaw architecture overview is useful context here: the Gateway coordinates those separate layers. Treat the tool result as a contract at that boundary, not as a private implementation detail of one plugin.
For an operator, the first check is whether an oversized result fails visibly and safely. OpenClaw’s current FAQ points to openclaw status --all for a shareable diagnostic report with tokens redacted, and to openclaw logs --follow for local investigation. Use those surfaces to identify the failed layer. Do not paste a giant raw response into a shared chat while trying to diagnose a size problem.
This post is also intentionally narrower than provider-response reliability, which covers HTTP provider bodies and failure classification. Tool output limits start after a tool has completed: they determine what useful evidence crosses into agent context. For the surrounding timeout problem, see AI agent timeouts. For a security review of what diagnostic records may expose, see AI agent diagnostic privacy.
Test the limit as a normal failure mode
A tool contract is not proven by a happy-path response. Add tests that deliberately produce large lists, a binary-looking error page, a slow stream, and an artifact that exceeds the chat-readable budget.
Check four outcomes:
- The runtime stops reading at the intended bound.
- The agent receives a typed result that says whether it got a page, a summary, an artifact, or an error.
- The continuation path works with the same authorization rules as the first call.
- Logs retain identifiers and a safe failure reason without retaining credentials or the full oversized body.
The last point is easy to underweight. Large error responses often include copied request context, HTML from a gateway, or upstream diagnostics. The OpenClaw diagnostic privacy guide explains why a bounded error record should still be treated as a security boundary.
FAQ
Should every AI agent tool have the same output limit?
No. A tool that returns a list of IDs can use a small page. A document-search tool may need a larger excerpt. A generated report should usually return an artifact reference. Use the smallest result that lets the next step make a sound decision, then expose a safe continuation path.
Is truncation always a bug?
No. Silent truncation is the bug. A deliberate bounded page with truncated: true, a total or cursor, and a follow-up tool is often the most reliable design. The agent knows what it saw and what it did not see.
Should a tool summarize data before returning it?
Only when the next step needs a conclusion rather than record-level selection. Keep enough metadata and a raw continuation path so the agent can verify a surprising summary instead of treating it as ground truth.
How does this help a self-hosted OpenClaw deployment?
It keeps one plugin, browser fetch, or integration from consuming an unreasonable share of Gateway memory and context. It also gives operators a clearer failure record and gives the agent a way to continue with a smaller, more useful view of the data.