[DOCS] Agent SDK Read tool docs omit size-cap behavior and `parts` output

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/typescript

Section/Topic

Read tool reference (FileReadInput / FileReadOutput) in the Agent SDK TypeScript and Python references

Current Documentation

The TypeScript reference currently says:

type FileReadInput = { file_path: string; offset?: number; limit?: number; pages?: string; }; Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use pages for PDF page ranges (for example, "1-5").

Later on the same page it also says:

type FileReadOutput = ... | { type: "parts"; file: { filePath: string; originalSize: number; count: number; outputDir: string; }; }; Returns file contents in a format appropriate to the file type. Discriminated on the type field.

The Python reference currently documents only:

{ "file_path": str, "offset": int | None, "limit": int | None, } Output (Text files): { "content": str, "total_lines": int, "lines_returned": int } Output (Images): { "image": str, "mime_type": str, "file_size": int }

What's Wrong or Missing?

Changelog v2.1.119 includes: Fixed SDK/bridge read_file not correctly enforcing size cap on growing files.

That indicates SDK/bridge read_file / Read calls have a real size-cap behavior that callers can hit, but the current docs never explain:

A. When the size cap applies

The reference does not say that large reads can be capped, or that files growing during a read can still hit that cap.

B. What type: "parts" means in practice

The TypeScript reference exposes a parts variant with originalSize, count, and outputDir, but it does not explain when this variant is returned or how callers should handle it instead of inline content.

C. Python/TypeScript parity

The Python reference omits the corresponding large-file/PDF/alternate-output behavior entirely, so Python SDK users are more likely to assume Read only returns inline text or image payloads.

Suggested Improvement

Add a short note to the Read tool docs that:

• Read enforces a maximum inline payload size
• files that exceed that cap can return type: "parts" with outputDir, count, and originalSize instead of a single inline payload
• this can also matter for files that grow while they are being read
• offset and limit are the recommended way to page through large text files
• the Python and TypeScript SDK references should document the same Read inputs and output variants

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/typescript | Read reference lists a parts output shape but does not explain the size cap or when segmented output is returned |
| https://platform.claude.com/docs/en/agent-sdk/typescript | Same Agent SDK TypeScript reference gap |
| https://code.claude.com/docs/en/agent-sdk/python | Python Read reference omits large-file / alternate-output behavior entirely |
| https://platform.claude.com/docs/en/agent-sdk/python | Same Python reference gap |

Total scope: 4 pages affected

Source: Changelog v2.1.119

Changelog entry: Fixed SDK/bridge read_file not correctly enforcing size cap on growing files