Replace line-based tool output truncation with token-based limits
Resolved 💬 40 comments Opened Nov 9, 2025 by provencher Closed Nov 25, 2025
💡 Likely answer: A maintainer (github-actions[bot], contributor)
responded on this thread — see the highlighted reply below.
Problem
Currently, Codex uses a naive line-based truncation mechanism for tool outputs:
- Hard limit: 256 lines OR 10 KiB (whichever is hit first)
- Strategy: Head+tail truncation showing first 128 lines + last 128 lines
This was introduced in commit 957d449 (August 2025, v0.24.0).
Why This Is Problematic
- Arbitrary line limits don't correlate with token usage: A tool output with 256 short lines might only be 1-2k tokens, while another with 100 long lines could be 10k+ tokens. Line-based truncation doesn't account for actual context window pressure.
- Forces excessive tool calls: When the model needs comprehensive information (e.g., reading a large file, analyzing test output), it must make many sequential tool calls to work around the 256-line limit, significantly slowing down task completion.
- Head+tail strategy loses critical context: Showing first 128 + last 128 lines with a gap in the middle can hide the most important information, especially for:
- Build outputs where errors appear in the middle
- Test results with failures scattered throughout
- File contents where key logic is in the middle sections
- Recently made worse for MCP tools: In v0.56, this truncation was extended to MCP tools (previously they weren't truncated until the next turn), making the MCP experience significantly worse.
Proposed Solution
Replace line-based limits with token-based limits similar to how Claude Code handles this:
// Instead of:
const MODEL_FORMAT_MAX_LINES: usize = 256;
// Use:
const MODEL_FORMAT_MAX_TOKENS: usize = 25_000;
Benefits
- Aligns with actual context window constraints: Tokens are what matters for the model, not lines
- More efficient information transfer: 25k tokens could be 500+ lines of dense code or logs
- Fewer tool calls needed: Model can digest more information per call
- Faster overall execution: Less back-and-forth means faster task completion
Implementation Notes
- Use the existing tokenizer in
codex-rs/core(already available for truncation in other parts of the codebase) - Keep the 10 KiB byte limit as a secondary safeguard to prevent pathological cases
- Consider keeping head+tail strategy but with token-based boundaries instead of line-based
- Apply consistently to all tools (built-in and MCP) from the start
Impact
This change would significantly improve:
- Speed: Fewer tool calls means faster completion
- Accuracy: Model sees more context per call, makes better decisions
- MCP experience: Currently degraded in v0.56 due to aggressive line truncation
- User experience: Less waiting, better results
References
- Current truncation code:
codex-rs/core/src/context_manager/truncate.rs - Original line limit introduction: commit 957d449 (Aug 2025)
- Extension to MCP tools: commit 1c8507b (Oct 2025, v0.54.0)
- Claude Code tokenizer usage
40 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
Since upgrading to 0.57 it seems tool calls are truncated.
This makes the usage of MCP useless.
Can we mark this as a high priority issue!!!!
because Linear truncates the issue description after ~10 KB, so the plan
content is cut off. I need the full ## PLAN text (or a smaller version)
pasted here or available through another endpoint before I can parse the
tasks and continue the /implement loop.
This breaks our complete development flow.
Downgrading to version ≤ 0.49does not have these issues.
So it seems it was introduced >= 0.50–0.55
Can we get this labeled as bug please.
⚠️⚠️ Lets take a simple yet fatal use case:
Relevant commit that introduced the issue: https://github.com/openai/codex/commit/1c8507b32a1b880283d89546db6b510a03a0d935
problematic PR
https://github.com/openai/codex/pull/5979
@aibrahim-oai can you have a look into this please.
We had a big discussion today during a meetup this seem to affect a lot of people.
Thanks for the report @provencher and @SaschaHeyer. This is on our list of priorities, I am hoping to get an update out next week.
Out of curiosity, what limit you think is reasonable for this?
Thanks for jumping on it @aibrahim-oai
Personally I’d rather not have an artificial limit at all.
The model’s context window is the only cap that really matters, and forcing every tool to pre-chunk defeats the point of MCP.
If you need a guardrail for runaway outputs, I’d prefer a warning or optional setting, not hard truncation.
In other words, give users the choice: no limit by default, with an opt-in ceiling for people who care more about latency/cost than completeness.
For teams like ours, the priority is completeness.
Out of curiosity, what drove the original 10 KB/256-line cap? Was it mainly defensive (latency/cost), or something else?
Imo, a token based limit of 25k tokens to match Claude Code is much more reasonable, but in any case having something configurable makes sense. Consistency between these tools is important for MCP server builders
That limit is our observations to what produce the best results without overwhelming the model. Poorly designed MCPs can pollute the context and overwhelm the model, ultimately degrading the UX. Most users won't realize or understand what the MCP is doing.
imo, there should be a default limit and MCPs should provide pagination tools that models can call in parallel in case it needs more context. For now, we will add configuration to unlock use cases like you guys
My apologies in advance for being that annoying person posting AI replies but here is the important part:
MCP pagination doesn’t apply to tool outputs. The MCP spec paginates list operations (resources/list, tools/list, etc.)—not tools/call. Large tool results should be returned as resource links or embedded resources, not paginated tool result pages. Client‑side truncation before feeding an LLM is compatible with the spec, but “use MCP pagination for tool outputs” would not be.
https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination#pagination
Bottom line
Full Reply for reference:
====================
Here’s my neutral take on Issue #6426 (“Replace line‑based tool output truncation with token‑based limits”) and what I’d recommend.
---
Unbiased feedback on the issue
What the issue gets right
MODEL_FORMAT_MAX_LINES/MODEL_FORMAT_MAX_BYTESand notes only content sent to the model is truncated. ([GitHub][1])globally_truncate_function_output_items(...), which walks tool result content items and applies a single total‑bytes budget before building model input. Review comments also flagged image handling and ordering concerns. ([GitHub][2])Minor corrections/clarifications
Feasibility of the proposed solution
MCP angle (important context)
resources/list,tools/list, etc.)—nottools/call. Large tool results should be returned as resource links or embedded resources, not paginated tool result pages. Client‑side truncation before feeding an LLM is compatible with the spec, but “use MCP pagination for tool outputs” would not be. ([Model Context Protocol][6])---
Recommendation
Short version: Adopt token‑based truncation for text content items before model input, keep a byte‑limit failsafe, and adjust the aggregator to preserve ordering, salience, and tail visibility—plus document MCP best practices for large outputs.
1) Replace line caps with a token budget (retain a byte fuse)
Why: Tokens map to real context pressure; the byte fence alone causes brittle mid/tail loss. The tooling to measure tokens is already present elsewhere in Codex. ([OpenAI Developers][5])
2) Use head+tail at the token level and protect the tail
3) Preserve original item order and provenance across content items
4) Make it configurable (and easy to debug)
model_input_token_budget(andmodel_input_byte_fuse) in config/TOML and surface a/statusor debug line showing what got truncated and by how much. This helps advanced users tune throughput vs. context.5) Document MCP server best practices for large results
resource_linkor embeddedresourceplus a concise textual summary, rather than giant text blobs. This is squarely in‑spec and reduces truncation pressure on the client. ([Model Context Protocol][8])6) Rollout & tests
a) few long lines (byte fuse), b) many short lines (token budget), c) middle‑of‑log error preservation, d) multiple content items with order retention, e) base64 image handling (skip/resize), f) MCP tool output with resource links.
---
Bottom line
For reference: the issue text and commit links summarize today’s behavior and the proposed change, and the PR and release notes confirm the MCP‑wide truncation behavior now in Codex. ([GitHub][4])
[1]: https://github.com/openai/codex/commit/957d44918d334e89473b9abad14df96f843a19aa "send-aggregated output (#2364) · openai/codex@957d449 · GitHub"
[2]: https://github.com/openai/codex/commit/1c8507b32a1b880283d89546db6b510a03a0d935 "Truncate total tool calls text (#5979) · openai/codex@1c8507b · GitHub"
[3]: https://github.com/openai/codex/releases/tag/rust-v0.54.0 "Release 0.54.0 · openai/codex · GitHub"
[4]: https://github.com/openai/codex/issues/6426 "Replace line-based tool output truncation with token-based limits · Issue #6426 · openai/codex · GitHub"
[5]: https://developers.openai.com/codex/changelog/ "Codex changelog"
[6]: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination "Pagination - Model Context Protocol"
[7]: https://github.com/openai/codex/pull/5979 "Truncate total tool calls text by aibrahim-oai · Pull Request #5979 · openai/codex · GitHub"
[8]: https://modelcontextprotocol.io/specification/2025-06-18/server/tools "Tools - Model Context Protocol"
Thank you for the detailed feedback! You're correct that commit 1c8507b landed in v0.54.0, but there was an additional change that I should clarify.
The v0.56 Change
While the truncation mechanism () was added in v0.54.0, there was a significant architectural change in v0.56 (commit 1a89f700, PR #6229) that changed when truncation happens in the pipeline.
Before v0.56 (including v0.54 and v0.55):
ConversationHistory::record_itemsduring history recordingAfter v0.56:
context_managermodule created with dedicatedtruncate.rsresponse_processing.rs)This explains why MCP users noticed a significant experience change specifically in v0.56, even though the truncation limits themselves were established in v0.54.0.
Just a note @aibrahim-oai. Hopefully your config option is a per-mcp one, like the tool timeout (which is 60s and I think too low imo, but the config is there so not a huge issue). I think it makes sense for each server to have it's own truncation limits.
I would like to echo the need for global and MCP level controls when you allow for user settings. There are plenty of tools I would not want to give extra room to pollute context. RepoPrompt is one of the best tools designed to keep context clean and relevant (it makes the codex experience so much better for hard problems). So some way to change global and tool level limits would be nice.
Personally I would like Codex to use RepoPrompt MCP more within the overall flow. In the earlier pre-0.45 releases Codex would even use RP over its own internal tools. This can be really beneficial in certain cases when you want different tools integrated (the way some people prompt agents to use an alternative bash tool).
Glad it's been so beneficial to your dev work!
I have another open issue to help with this, but it's been just sitting stagnant for a while. If there was a flag that could disable built in tools, or at least the read file, search and apply_patch tools, codex would have to make better use of RP.
The reason it's gotten less prone to using RP tools is that they strengthened the system prompt to push Codex to use the specific built in tools provided.
So a PR was accepted arbitrarily discarding what could be critical tool response context in an AI tool people are using to code their software and admin their systems? Is the agent even clued into the fact that its tool call responses are being truncated in this manner? It sounds to me that even if the agent wanted to go out of its way to make a new request just to get the piece of response it needed (that would be bad enough), it could not do so, and maybe (even worse) wouldn't even know it needed to in the first place.
Also, forcing servers to provide that kind of pagination is not good. It greatly expands the scope of thousands of MCP projects into a stateful regime where the client could have just had such a simple buffer to page.
Let's close our eyes for a moment, and imagine some worst case scenarios, leading to catastrophic failures. Now realize that these catastrophes have almost certainly already occurred, and the second-order effects of that PR rippling out decades into the future of humanity.
my gods. what have we done?
This truncation make the usage of MCP like context7 useless, i tried the codex with version > 0.56. And when using the context7 , the document that fetched is truncated, resulting the model thinking there isn't explanation or official implementation, so the model make it by itself which cause another problem. But when i use the 0.55 version it just go straight implementing the correct solution as it gather full context from documentation using context7 MCP.
This truncation has indeed made the use of MCPs utterly useless. I used playwright-mcp, and when the tool calls
browser_snapshot, it will truncate the page details halfway through, and the model simply is unable to automate anything in that web-page, as it can't see the full tree.As revealed at https://github.com/openai/codex/issues/5913, it is related to how the model was fine-tuned (and their own in-house tests). By observing the logs, you can see that, as trained, the model tends to make tool requests for 256-line chunks. When truncation happens, Codex indicates where the removed content was before sending it to the model. These markers ensure the model knows the content was omitted and how. We expect the model to recognize this and request the missing content using another tool request. The model does requests the missing content using another read tool request, but not always. There are also other potential drawbacks that I outlined at https://github.com/openai/codex/issues/591:
As a power user this worries me. I agree on some reasonable upper limit due to not having pagination but I can now see how this has affected my output. The model has been receiving a partial picture of our MCP server data
Is this the same issue referenced in https://x.com/badlogicgames/status/1989858718096228597?s=20 and acknowledged by https://x.com/thsottiaux/status/1989940347494084683?s=20
This issue is so bad that, in my experience, codex now can no-more reliably differentiate between a simple unit test suite run that succeeded or failed. It will run the test CLI command and simply miss error messages contained in the corresponding command output, even in a completely fresh session (no context pollution). It will happily claim (and insist even when presented with contradicting evidence) that the unit tests passed, and that is 100% reproducible in every single session.
Codex will now also happily ignore that the test script process exit code is actually non-zero because it lost the "intelligence" to use it's own shell tool in a way that simultaneously captures both exit code and output text correctly.
The future of abundant machine intelligence seems like marketing pitch and the reality looks more like we are increasingly delegating authority to arbitrary idiotic decisions that humans nonetheless blindly assume to be intelligent.
This is ridiculous and is seriously hurting Codex's usefulness:
https://x.com/badlogicgames/status/1989866831104942275
Must watch for everyone in this thread
Yep, i've been dealing with this for a good while. In fact i just recorded exactly that: https://github.com/openai/codex/issues/6721#issuecomment-3539427385
Ah.. That's likely the explanation for the increased usage people are complaining about every second on /r/codex. It's like an airport over there.
I'd like to add some input here, for me particularly, if this is the cause of the usage being drained rapidly, I did notice a major behavior change after an update I believe from 0.46 onward, I saw in the changelog there were changes to the agent behavior. Namely, when I would run exec with a large context prompt in the terminal, I would not see a response for an extended period of time, and instead see blank newlines being created what seem like hidden responses. This started happening post upgrading to 0.46. Then after a while, there would be a sudden burst of responses that show up, sometimes 10 or more. I didn't know this was associated with the usage bug, but now it seems related. Once my usage gets reset, which I have to wait because all my usage gets used up so fast now, I will try running my workflow again using v0.45 and see if the usage is still rapidly drained.
Edit: I believe it was either 0.46 or 48 that caused this issue to begin occurring. So it may have been after 0.45 that this began happening for me. I will revert back to confirm once I have tested which version caused the change and try to pinpoint the possible cause.
And fyi - I do not use MCP at all, and I still have to deal with this issue. This affects me greatly and my workflow and I use exclusively Codex exec with a large prompt input. With a particularly large prompt, where it is over 120k tokens, it seems to drain my usage limit exponentially faster than with smaller context usage.
My original report which I am posting here for the first time. I previously sent this to @tibo-openai on Reddit. I should've posted it here on Github in an issue:
I am continuing to investigate further what could be the cause from each of these updates (v0.46 or 48).
In the likely scenario where the codex team is dogfooding and running its own test suite via the codex-cli, the codex-cli could now happily proclaim that codex-cli itself has no test failures. Ship it. Recursive progress. AGI achieved :-)
@aibrahim-oai can you communicate any ETA for the fix?
Why not implement pagination for the model for all tool calls inside Codex?
I.e., when the Codex harness executes a command on the model's behalf, it could keep the whole output in a buffer, and show the model the truncated output with clear instructions to the model on how to request the rest in pages.
That saves the model having to figure out for every command a different way of requesting pages, and it saves the model from having to re-run / re-request the same command multiple times.
Sadly, not every tool or command has inbuilt pagination. If this is so crucial to the model's functioning, the harness should be providing this service for the model.
We are working to land a series of improvements this week, alongside other exciting things. I expect it to land before Thursday, but no guarantees. It's at the top of our list.
Before other exciting things I rather get a hotfix for that existing issue. I have the feeling this does not have the right priority Open AI internally.
@tibo-openai the current state of Codex with this truncation bug makes certain types of development practically impossible. For example ingesting large and complex xml with no existing documentation, debugging graphql with large mutations, etc. I've also noticed the Codex with this truncation issue the agent tends to go in circles a lot and creates parallel implementations (my LOC ballooned while testing and my Pro usage is much more aggressive for the same amount of use not to mention no sense of progress of the task at hand, just circles). The bug also makes the test suite in my project much less effective when I want to iterate against the test suite.
I understand the need to address runaway context as a tool but not everyone is doing the same kind of development that fits in this arbitrary context window and I imagine some people use it for agentic workflows like say analyzing ad account performance or something that makes it impossible to fit or get predictable behavior.
If we are simply given an "opt out opportunity" this will not be a fundamental solution and some people less technically inclined doing the kind of development this bug aggravates will just be left with the impression that Codex sucks and seek alternatives.
I hope the team comes up with a more sophisticated solution that accounts for all second order effects as best it can.
Not to mention that it ignores failing tests and lint violations, and skips over comments on PRs.
It's doubly frustrating because the model doesn't know that it is missing important information, and the user is not made aware of the fact that the model is being denied the information.
Hey everyone! Thanks for waiting and for the feedback. In
v0.60.0, we pumped the default for Codex models to 10k tokens. Almost 4x the previous limit. You can configure it also using this config valuetool_output_token_limit. Please let us know how does this work for you.@aibrahim-oai this is indeed great news. Is it part of the latest release already?
Good to see we configure it as well.
yes
Thanks for the quick work! Well done
Thanks for the quick turnaround
Ok so there's one last issue with this release @aibrahim-oai
The config for the token limits is not per-server but global.
@aibrahim-oai thank you and the team so much for the stellar effort you put in! This was a huge release but very smooth and I've loved everything done with this release so far both with the cli and the model. Still in shock.
That said @provencher 's comment above is the only minor request I have and some people have reported the upper bound for 'tool_output_token_limit = 25000' is actually 10K regardless of the value. Can't personally confirm and everything is so smooth so it doesn't feel as urgent. However, for the sake of completeness I think we would all appreciate you taking a look when you can.
Once again, thank you for the excellent work. Seriously impressed by what you've accomplished with this major release all around.
Is there any recommended value here for
tool_output_token_limit?I have good results with 25k tokens, but I do only use the Repo Prompt mcp, and it's already quite token efficient.
fwiw structured MCP output helps a lot with this. I built
https://github.com/Dave-London/pare — MCP servers for git, npm, test runners, build tools etc that return typed JSON via structuredContent instead of raw CLI text. Cuts 70-90% of tokens on verbose commands like git log, test output, lint results. Every token saved on tool output is more room for actual reasoning.
Ran into this exact problem — a 256-line git log might only be 2k tokens, but a dense build output at 100 lines could be 10k+. Line counts are a terrible proxy. We built Pare — MCP servers that return structured JSON from CLI tools with
outputSchema+structuredContent, cutting output tokens by up to 92%. Might be useful as a reference for what "token-aware" tool output could look like.