D2 · Tool Design & MCP › Cluster 3 · Tool Results & Error Handling

3.3 · Large / Structured Results & Truncation

Keep results lean

CONCEPT Every result block lives in the transcript forever

A tool_result isn't consumed and discarded — it's appended to the conversation and re-sent as input tokens on every subsequent turn. Dump a 40 KB JSON blob into a result and you pay for it again on turn 2, turn 3, and every turn after, while burying the two fields Claude actually needed. The design goal for tool results is the opposite of "return everything just in case": return only high-signal information.

Anti-pattern: return json.dumps(full_api_response) — hundreds of nested fields, internal cursors, opaque IDs. It wastes context and makes Claude hunt for the signal.
Pattern: truncate, summarize, or project down to the fields that inform Claude's next step. Return semantic, stable identifiers (slugs, UUIDs) rather than opaque internal references.

CONCEPT Three levers for a lean result

LeverWhat it doesUse when
TruncateCap rows/chars and say what was cut ("...+920 more; refine your query")Long lists or logs where the head is representative
SummarizeReturn an aggregate or digest instead of raw recordsClaude needs the shape/answer, not every row
Project (structured)Return a small object with only the needed fieldsAn API gives 200 fields; Claude needs 4
🔑 "Structured content" here means a deliberately shaped small payload — a trimmed JSON object or a few typed fields — not the raw upstream response. Give Claude the schema it can act on, not the firehose.

CONCEPT When the payload is genuinely huge

If a result is inherently large (a whole file, a big dataset), don't inline it. Better shapes:

DIAGRAM Shrink before it enters context

flowchart TD RAW["Raw tool output
(large / deeply nested)"] --> Q{"Fits in a lean result?"} Q -->|"yes, small"| PASS["🟢 Return as-is"] Q -->|"no — too big"| SHR{"Which lever?"} SHR -->|"list/log"| TR["Truncate + note what was cut"] SHR -->|"needs the gist"| SM["Summarize / aggregate"] SHR -->|"200 fields, need 4"| PR["Project to a small object"] SHR -->|"whole file/dataset"| HD["🔵 Return handle / preview + pointer"] TR --> OUT["Lean tool_result"] SM --> OUT PR --> OUT HD --> OUT classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef info fill:#d0e7ff,stroke:#3d8bfd,color:#0a3d7a; class PASS ok; class HD info;

CODE Project + truncate instead of dumping JSON

def search_orders(query):
    rows = api.search(query)              # upstream: 900 rows × 60 fields each

    # ❌ DON'T: return json.dumps(rows) — huge, re-billed every turn

    # ✅ DO: project to the fields Claude needs, truncate, and signal the cut.
    lean = [
        { "id": r["order_id"], "status": r["status"], "total": r["total_usd"] }
        for r in rows[:20]
    ]
    note = "" if len(rows) <= 20 else f"...+{len(rows) - 20} more. Refine the query to narrow."

    return { "type": "tool_result",
             "tool_use_id": block.id,
             "content": json.dumps({ "orders": lean, "note": note }) }

TRADE-OFFS Dump everything vs. curate

✅ Curated / lean result

  • Cheap on every subsequent turn
  • Claude finds the signal fast
  • Higher accuracy, less distraction

⚠️ Dump the raw payload

  • Zero shaping work up front
  • But: re-billed context bloat each turn
  • Buries relevant fields; can degrade reasoning
Never silently truncate content you were asked to hand off wholesale (e.g. a file the user needs in full). Truncate the tool result view, and give Claude a pointer to fetch the rest — don't quietly drop data it needs.

EXAM TRAPS

Trap: "Return everything so Claude has full context." → Bloated results waste context and bury the signal. Return only high-signal fields; the result is re-billed every turn.
Trap: Truncating with no marker. → If you cut a list, say so ("...+920 more") so Claude knows the view is partial and can refine or paginate.
Trap: Returning opaque internal reference IDs. → Prefer semantic, stable identifiers (slugs/UUIDs) Claude can reuse; internal handles it can't reason about are dead weight.
Trap: Inlining a whole large file/dataset. → Return a handle or preview + pointer and let a follow-up tool fetch the slice that's actually needed.

PRACTICE

Q1 · A search tool can return 900 rows. What do you send back, and why not all 900?

A projected, truncated view — e.g. the top 20 rows with only the fields Claude needs, plus a "...+880 more" note. All 900 (× every field) would be re-billed as input tokens on every later turn and bury the relevant records.

Q2 · What does "structured result" buy you over dumping the raw upstream JSON?

A small, deliberately-shaped object exposes exactly the fields Claude must reason over, using stable identifiers. Raw JSON drags in nested internals and opaque IDs that cost tokens and distract the model.

Q3 · The result is a 5 MB file. How do you keep it out of the context window?

Don't inline it. Return a handle/path or a preview plus a pointer, and let Claude call a follow-up tool to fetch the specific slice it needs — the same pattern MA MCP tools apply automatically above ~100K tokens.