docs: correct what --screenshotFormat reduces (#2617)

`--screenshotFormat` says JPEG and WebP "helps reduce context size in AI
conversations". The byte saving is real, but it does not reach the
context: image tokens scale with the image's dimensions, not with the
size of the encoded payload.

Token delta on each Claude turn that followed exactly one image, with
the surrounding text small enough that the image dominates it, grouped
by pixel count so only the format differs:

| pixels | format | n | median bytes | median tokens |
| --- | --- | ---: | ---: | ---: |
| 1.5-1.8 MP | jpeg | 115 | 326 KB | 2362 |
| 1.5-1.8 MP | png | 298 | 357 KB | 2361 |
| 2.5-2.8 MP | jpeg | 45 | 444 KB | 3574 |
| 2.5-2.8 MP | png | 24 | 252 KB | 3604 |

Same pixels, same cost. Each delta carries a small fixed per-turn
overhead, so read the pairs against each other rather than as absolute
image cost. The formats come from separate captures rather than one
image encoded twice, so the byte column shows only that cost ignores it
– in the second pair the larger files are the cheaper ones.

The numbers are
[Claude](https://platform.claude.com/docs/en/build-with-claude/vision)'s,
but [GPT](https://developers.openai.com/api/docs/guides/images-vision)
and [Gemini](https://ai.google.dev/gemini-api/docs/tokens) price images
the same way, by pixel dimensions in patches or tiles. Neither charges
on encoded bytes.

`--screenshotMaxWidth` just below promises the same thing and does
deliver, since it changes the dimensions.

New wording:

> Override the default output format used by take_screenshot when the
caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG,
which reduces transfer and storage size. To reduce context size use
--screenshotMaxWidth / --screenshotMaxHeight, since image tokens scale
with dimensions rather than encoded bytes. Unset preserves the existing
default ("png").

`docs/configuration.md` is generated from that description and updated
to match.
This commit is contained in:
Thomas Bachem
2026-09-02 08:01:43 +00:00
committed by GitHub
parent 05d9e55581
commit c5757770b0
2 changed files with 2 additions and 2 deletions
+1 -1
View File
@@ -186,7 +186,7 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Default:** `true`
- **`--screenshotFormat`/ `--screenshot-format`**
Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").
Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which reduces transfer and storage size. To reduce context size use --screenshotMaxWidth / --screenshotMaxHeight, since image tokens scale with dimensions rather than encoded bytes. Unset preserves the existing default ("png").
- **Type:** string
- **Choices:** `jpeg`, `png`, `webp`
- **Default:** `false`
+1 -1
View File
@@ -320,7 +320,7 @@ export const mcpOptions = {
screenshotFormat: {
type: 'string',
description:
'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").',
'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which reduces transfer and storage size. To reduce context size use --screenshotMaxWidth / --screenshotMaxHeight, since image tokens scale with dimensions rather than encoded bytes. Unset preserves the existing default ("png").',
choices: ['jpeg', 'png', 'webp'] as const,
},
screenshotQuality: {