[DOCS] Agent SDK MCP tool result docs omit `structuredContent` alongside image content

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Create a custom tool handler return shape and Return images and resources

Current Documentation

The docs currently say:

- Handler: the async function that runs when Claude calls the tool. It receives the validated arguments and must return an object with: - content (required): an array of result blocks, each with a type of "text", "image", or "resource". See [Return images and resources](#return-images-and-resources) for non-text blocks. - isError (optional): set to true to signal a tool failure so Claude can react to it.

Later on the same page, it also says:

The content array in a tool result accepts text, image, and resource blocks. You can mix them in the same response.

The TypeScript reference currently documents CallToolResult as:

type CallToolResult = { content: Array<{ type: "text" | "image" | "resource"; // Additional fields vary by type }>; isError?: boolean; };

What's Wrong or Missing?

These pages document MCP/custom tool results as if they only contain content and optional isError.

That is outdated for Claude Code: the changelog already notes support for MCP structuredContent in tool responses, and v2.1.128 specifically fixed a bug where images were dropped when a server returned both structured content and content blocks.

Because the docs never describe structuredContent in the tool result shape, they also never explain that structuredContent can be returned together with content, including image blocks. That leaves tool authors without guidance for a supported response shape and makes the v2.1.128 fix effectively undiscoverable in the reference docs.

Suggested Improvement

Update the custom tools guide and CallToolResult reference to document the full supported MCP tool result shape for Claude Code.

At minimum:

1. Add structuredContent to the documented tool result contract.
2. State explicitly that structuredContent and content can be returned together in the same result.
3. Add an example that returns machine-readable structuredContent plus a content array containing an image block.
4. Mention that this mixed response shape is supported in Claude Code and that the image-preservation fix shipped in v2.1.128.

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 | 31-35, 440-451 | Handler return contract and image/resource result guidance omit structuredContent |
| https://code.claude.com/docs/en/agent-sdk/typescript | 2444-2455 | CallToolResult omits structuredContent |
| https://platform.claude.com/docs/en/agent-sdk/custom-tools | 31-33, 445-457 | Parallel Agent SDK guide omits structuredContent while documenting image blocks |
| https://platform.claude.com/docs/en/agent-sdk/typescript | 2273-2284 | Parallel CallToolResult reference omits structuredContent |

Total scope: 4 pages affected

Version context:

• https://code.claude.com/docs/en/changelog documents Support MCP structuredContent field in tool responses under v2.0.21.
• The v2.1.128 changelog entry indicates Claude Code also needed a fix for mixed structuredContent + content-block responses when those content blocks include images.