Skip to main content

​
The new problem

If a file contains 20,000 lines, does read_file send all 20,000 lines to the model? No—not necessarily. read_file is a name, not a standard API. An implementation might return the entire file, a requested range, or a capped excerpt. The model only sees the content the harness includes in its observation. Reading bytes on disk and putting those bytes into the model’s context are separate operations. For this guide, use bounded reads with explicit continuation, and search for relevant code before expanding the context.
The contracts and limits below are a proposed design for this guide, not an industry standard. For how two production agents bound their reads, see the comparison table in Essential tools.

​
Will read_file read the whole file?

Only when the implementation allows it and the file fits the budget. A useful contract accepts a range and applies a hard output cap even if the caller asks for more.
In this example, lines are one-based, max_lines is a count, and the byte limit applies to the returned content. The harness validates and clamps these values. The caller cannot disable the hard maximum by passing an enormous number. An illustrative response for a large file could be:
The content above is abbreviated for display. A real tool returns the exact requested text, not an invented summary. truncated here means that unread content remains after the returned range; eof means the read reached the end of the file. Keeping these semantics explicit prevents “I read the file” from silently meaning “I saw its first few lines.”

​
What limits should we start with?

As an initial policy, try 200 lines and 16 KiB of content per read, whichever is reached first. These are design examples to tune against real tasks, not proven optimal values. Reserve context for the user request, prior observations, reasoning, and the response. A byte cap is not a token cap: also enforce the model’s total input budget when assembling context. Return complete lines where possible. If a single minified line exceeds the cap, return a structured line_too_long error with a recovery hint, or use a separate byte-range reader with a byte cursor. Advancing to the next line after returning half a line would silently lose content. Do not compute an exact total line count on every read if doing so requires scanning a huge file. A reliable continuation cursor and eof are enough. Small files can be returned in full when they fit the same limits.

​
How does the agent understand a large file?

It builds evidence incrementally. It does not need every line for every task, but a small excerpt is not proof of whole-file understanding.

​
Example: a session expires too early

  1. Use find_files for likely auth or session paths. Avoid dumping the entire repository tree.
  2. Search those paths for expiresAt, the observed error, or the validation function. Return a bounded number of matches with line numbers.
  3. Read the complete relevant function around the best match. If the range cuts through the function, expand it.
  4. Inspect the timestamp type, configuration, callers, and nearby tests. A conversion bug may live outside the first matching file.
  5. Patch the smallest justified change, review the diff, and run the relevant tests. Report what was verified and what remains uncertain.
For a broad refactor, more of the repository may be necessary. Retrieve additional ranges deliberately and keep concise notes with paths and line references. Summaries help navigation; reread the exact current source before editing it. If the task requires a whole-file audit, track coverage explicitly and do not claim completion after sampling.

​
What makes reading reliable?

Resolve paths inside the authorized workspace, including symlink targets. Identify missing, binary, unsupported, or unreadable files explicitly. Avoid sending binary data as if it were text. Attach a file version to every read, so a later edit can check that the file has not changed since. Edit & run tools in detail covers how edits use it.

​
How do we know the design works?

Exercise the read contract with a small file, a huge file, an oversized single line, an empty file, and a binary file. Check that every case either returns bounded, accurate content with a way to continue, or fails explicitly. Then evaluate actual tasks: can the agent find the relevant part of a large file without repeatedly retrieving irrelevant content?
Design decision: Bound every read, report whether content remains, and search before expanding. Never let a partial read pass for a whole-file read.

​
Sources and further reading

Anthropic’s Writing effective tools for agents recommends pagination, range selection, filtering, and truncation for large responses. The contracts and worked example on this page are this guide’s proposed implementation.

​
Continue learning

Repository access

Return to the topic that introduced read_file.

Harness controls

The next advanced topic: how the harness decides which actions run.