[DOCS] Custom tools docs do not explain unsupported MCP image MIME fallback

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Return images and resources / MCP tool-result image blocks

Current Documentation

The docs currently say:

The content array in a tool result accepts text, image, and resource blocks. You can mix them in the same response. | mimeType | string | Required. For example image/png, image/jpeg, image/webp, image/gif |

The same section also shows this TypeScript example:

const mimeType = response.headers.get("content-type") ?? "image/png"; return { content: [{ type: "image", data: buffer.toString("base64"), mimeType }] };

What's Wrong or Missing?

This section explains how to return inline image blocks, but it does not document what Claude Code does when an MCP tool returns an image MIME type that is not supported for inline visual rendering.

That gap matters because the example passes through the upstream HTTP content-type, which can easily be something like image/svg+xml. As of v2.1.144, unsupported MCP image MIME types no longer break the conversation; Claude Code saves that payload to disk and references the file in the tool result instead.

Without that note, MCP server authors can reasonably assume any image MIME type is acceptable as long as it is labeled as an image block, and users have no documentation explaining why some image outputs show up as file references instead of inline visual content.

Suggested Improvement

Add a short note in Return images and resources that distinguishes supported inline image MIME types from unsupported ones.

Suggested wording:

Claude Code renders inline MCP image blocks only for supported image MIME types such as image/png, image/jpeg, image/gif, and image/webp. If a tool returns an unsupported image MIME type such as image/svg+xml, Claude Code saves the payload to disk and returns a file reference in the tool result instead of inline visual content.

It would also help to update the fetch-image example so it does not imply that blindly forwarding any upstream content-type will always produce inline image output.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-sdk/custom-tools | 442-452, 489-499 | Documents image blocks and shows an example that forwards the upstream MIME type, but does not explain unsupported-image fallback behavior |
| https://code.claude.com/docs/en/mcp | 860-877 | Already documents file-reference fallback for oversized MCP results, which is a natural place to cross-reference the unsupported-image fallback added in v2.1.144 |

Total scope: 2 pages affected

Relevant behavior changed in v2.1.144.