Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Agent SDK MCP tool result docs omit `structuredContent` alongside image content [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#56158•Fetched 2026-05-05 05:56:40
View on GitHub
Comments
0
Participants
1
Timeline
5
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×5

Root Cause

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.

RAW_BUFFERClick to expand / collapse

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 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:

PageLine(s)Context
https://code.claude.com/docs/en/agent-sdk/custom-tools31-35, 440-451Handler return contract and image/resource result guidance omit structuredContent
https://code.claude.com/docs/en/agent-sdk/typescript2444-2455CallToolResult omits structuredContent
https://platform.claude.com/docs/en/agent-sdk/custom-tools31-33, 445-457Parallel Agent SDK guide omits structuredContent while documenting image blocks
https://platform.claude.com/docs/en/agent-sdk/typescript2273-2284Parallel 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.

extent analysis

TL;DR

Update the custom tools guide and CallToolResult reference to include structuredContent in the tool result shape, allowing it to be returned together with content, including image blocks.

Guidance

Example

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

Notes

The current documentation only mentions content and isError in the tool result shape, which is outdated and does not reflect the support for structuredContent in Claude Code.

Recommendation

Apply workaround by updating the documentation to include structuredContent in the tool result shape, as this will provide clarity and guidance for tool authors, making the feature easier to understand and use.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#index setup#retrieval issue#search optimization#API routing#API middleware

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Agent SDK MCP tool result docs omit `structuredContent` alongside image content [1 participants]