[DOCS] Read tool docs omit compact line-number output and unchanged re-read deduplication

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Read tool behavior, especially output formatting and token-saving behavior for unchanged re-reads

Current Documentation

The docs currently say:

| Read | Reads the contents of files | No |

Related context-usage guidance also says:

Code intelligence plugins give Claude precise symbol navigation instead of text-based search, reducing unnecessary file reads when exploring unfamiliar code. A single "go to definition" call replaces what might otherwise be a grep followed by reading multiple candidate files.

* As Claude works: each file read adds to context, path-scoped rules load automatically alongside matching files, and a PostToolUse hook fires after each edit.

No code.claude.com page currently explains that the Read tool now uses a compact line-number format or that unchanged re-reads are deduplicated to reduce token usage.

What's Wrong or Missing?

Changelog v2.1.86 says:

Read tool now uses compact line-number format and deduplicates unchanged re-reads, reducing token usage

The current docs cover the existence of the Read tool and give general advice about reducing file reads, but they do not document two behaviors that affect how users interpret Read output and reason about context costs:

A. Compact line-number output is undocumented

Users who inspect tool transcripts or compare current behavior against older behavior cannot find any reference that text reads now use a more compact line-number format.

B. Unchanged re-read deduplication is undocumented

The costs/context guidance still frames file reads as straightforward context growth, but it does not explain that repeating the same unchanged read is now optimized to avoid repeated token overhead.

This leaves the Read tool reference incomplete and makes the context-cost guidance harder to interpret for users trying to understand why repeated unchanged reads do not behave the same as first reads.

Suggested Improvement

Add a short note to the Read entry in the tools reference that documents:

• text file results include line numbers in a compact format
• re-reading an unchanged file is deduplicated to reduce repeated token usage
• this optimization affects context/cost behavior, so repeated unchanged reads are cheaper than distinct file reads

Then add a brief cross-reference or note in the context/cost docs clarifying that unique file content is what primarily grows context, while unchanged repeated reads are optimized.

Impact

Low - Minor confusion or inconvenience

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | Primary Read tool reference |
| https://code.claude.com/docs/en/costs | "Reduce token usage" guidance for minimizing file reads |
| https://code.claude.com/docs/en/context-window | Explains how file reads add to context |
| https://platform.claude.com/docs/en/agent-sdk/python | Agent SDK Read output currently says text content includes line numbers |
| https://platform.claude.com/docs/en/agent-sdk/typescript | Agent SDK Read input/output reference |

Total scope: 5 pages affected

Source: Changelog v2.1.86

Changelog entry: Read tool now uses compact line-number format and deduplicates unchanged re-reads, reducing token usage