[DOCS] Image input docs missing token-budget/compression details for pasted and attached images

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/common-workflows

Section/Topic

Work with images, plus the related image-input guidance in desktop, desktop-quickstart, and the Read tool docs.

Current Documentation

The docs explain how to provide images, but they do not explain how pasted/attached images are processed or that they now share the same token budget as images read via the Read tool.

common-workflows currently says:

Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content. 1. Drag and drop an image into the Claude Code window 2. Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v) 3. Provide an image path to Claude. E.g., "Analyze this image: /path/to/your/image.png"

desktop currently says:

Attach files: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt.

agent-sdk/typescript currently says:

Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks.

None of these pages describe image compression/downscaling behavior, token-budget limits for image inputs, or that pasted and attached images are now normalized to the same budget as images provided through the Read tool.

What's Wrong or Missing?

Claude Code v2.1.97 changed user-visible image behavior: pasted and attached images are now compressed to the same token budget as images read via the Read tool.

That matters because the current docs present paste, drag-and-drop, file attachment, and path-based image input as separate ways to add images, but they do not explain that these paths now converge on the same effective image budget.

Users working with screenshots, diagrams, or dense UI images cannot tell from the docs:

1. that pasted/attached images may be compressed before analysis,
2. that the Read tool path is now aligned with pasted/attached image handling, or
3. what consistency to expect when switching between these input methods.

Suggested Improvement

Add a short Image size and processing note to the main image-input docs, ideally in common-workflows and/or desktop, covering:

• pasted, dragged, and attached images are compressed to fit Claude Code's image token budget,
• images supplied via the Read tool are handled to the same budget,
• users should expect broadly consistent analysis across these input methods,
• large images may be resized/compressed before they are sent for analysis.

If there is a user-relevant size/fidelity caveat (for example, very large screenshots losing detail), document that explicitly where image workflows are introduced.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/common-workflows | Primary Work with images workflow for drag/drop, paste, and image-path input |
| https://code.claude.com/docs/en/desktop | Add files and context to prompts explains file attachments for images |
| https://code.claude.com/docs/en/desktop-quickstart | Quickstart repeats the image attachment and drag/drop guidance |
| https://code.claude.com/docs/en/interactive-mode | Documents the clipboard shortcut that inserts pasted images |
| https://code.claude.com/docs/en/best-practices | Recommends pasting or dragging images directly into the prompt |
| https://code.claude.com/docs/en/agent-sdk/typescript | Documents that the Read tool accepts image files, which is the comparison point named in the changelog |

Total scope: 6 pages affected

Source: Changelog v2.1.97

Exact changelog entry: Improved image handling: pasted and attached images are now compressed to the same token budget as images read via the Read tool