◉CLAUDE LABJP
●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API
Articles/API & SDK
⬡ API & SDK/2026-06-29Advanced

Let Claude Actually See the Images Your Tools Return — Use Image Blocks in tool_result and Cut Tokens by Roughly 10x

Stuffing a base64 string into a tool_result makes the same image cost roughly 10–20x more tokens. Here is how to return it as an image content block instead, with SDK code, a token-cost estimate, and the gotchas I hit in production.

Claude API148tool use5vision8tool_resulttoken optimization

✦ Premium Article

There is a trap in tool implementations that is surprisingly easy to miss: your tool returns an image, but Claude never actually sees it. I ran into this myself when I wrote a tool that lets an agent judge wallpaper thumbnails. The response came back fine, but the judgments were oddly vague. When I dug in, Claude was reading a long base64 string as text, not looking at the picture.

The annoying part is that a tool_result accepts almost anything, so the wrong shape still runs. It works, but it costs you. This article walks through how to return images so Claude genuinely sees them, with the actual numbers attached.

When your tool returns an image but Claude isn't looking

When you answer a tool_use, most implementations put a string into the content of a tool_result. For tools that return text, that is exactly right. But when you want to return an image, it is tempting to write this:

# Anti-pattern: stuffing the image base64 in as a "string"
tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use_id,
    "content": f"image data: {base64_png}",  # treated as text
}

The API will not raise an error here. Claude receives the base64 as text, and on the surface processing continues. But Claude never looks at the pixels, so it cannot make any judgment based on the image. Worse, those tens of thousands of base64 characters are billed as input tokens.

Reports in the official SDK repositories and community threads describe exactly this: tool-result images that are not converted into native image blocks and instead get sent as text, consuming around 15,000–25,000 tokens per image. The same image attached directly as a user message costs about 1,600 tokens, so the gap is roughly 10–20x. It is the classic case of paying ten times more for something that appears to work.

The correct shape is an image content block inside tool_result

The content of a tool_result accepts not just a string but an array of content blocks. Put an image block there and Claude recognizes it as an image and reads the pixels with its vision capabilities.

# Correct shape: make content an array and include an image block
tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use_id,
    "content": [
        {
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/png",
                "data": base64_png,
            },
        },
        {"type": "text", "text": "Here is the current thumbnail candidate. Rate its legibility."},
    ],
}

Two things matter: make content an array, and pass the image as an {"type": "image", ...} block. If you want to add a text note, just place a text block alongside it in the same array. On Claude's side, this image is handled exactly like an image a user attached, which means it is also billed at image rates rather than as tens of thousands of text tokens.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN
✦Why putting base64 into a tool_result as a string makes the image count as text and burns roughly 15,000–25,000 tokens per image, and how to avoid it
✦The real cost when you return it as an image block (around 1,600 tokens) plus a formula to predict tokens from width and height before you send
✦A working agent loop that shows wallpaper thumbnails and App Store screenshots to Claude, with the size limits, media types, and the not-rendered-to-users pitfall
Secure payment via Stripe · Cancel anytime
✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

or
Unlock all articles with Membership →
Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

Related Articles

⬡ API & SDK2026-06-13
Claude Vision API in Production — Implementation Patterns for Image Analysis, PDF Processing, and OCR
Implementation patterns for taking Claude's vision capabilities to production: choosing between Base64, URL, and the Files API, native PDF processing, schema-enforced extraction with Tool Use, batch cost reduction, and error recovery — all with working code.
⬡ API & SDK2026-11-18
Before Your Customers Pay Through Linked Billing: Reading a 402 or 403 to Find Whose Wallet Is Empty
Linked billing, released in beta on November 17, lets you choose who pays on every Claude API request through billing_policy. When a request billed to a customer comes back as a 402 or 403, here is how I work out which wallet is the cause, when to pay for it myself, and a small Python wrapper that keeps that decision in one place.
⬡ API & SDK2026-11-17
If You Rely on Claude's Text Watermark, Check temperature in the Request Body, Not Your Code
Since November 16, text from Opus 4.6, Opus 4.5, Sonnet 4.5, and Haiku 4.5 carries Anthropic's text watermark, but non-default temperature, top_p, or top_k may drop it. Here is how I log the request body once and decide.