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.
return json.dumps(full_api_response) — hundreds of nested fields,
internal cursors, opaque IDs. It wastes context and makes Claude hunt for the signal.CONCEPT Three levers for a lean result
| Lever | What it does | Use when |
|---|---|---|
| Truncate | Cap rows/chars and say what was cut ("...+920 more; refine your query") | Long lists or logs where the head is representative |
| Summarize | Return an aggregate or digest instead of raw records | Claude needs the shape/answer, not every row |
| Project (structured) | Return a small object with only the needed fields | An API gives 200 fields; Claude needs 4 |
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:
- Return a handle — an ID or path Claude can pass to a follow-up tool that fetches a slice.
- Return a preview + pointer — first N lines plus "full content at
/path". (Managed-Agents MCP tools do exactly this automatically when output exceeds ~100K tokens: the agent gets a truncated preview plus a file path toread.) - Pre-aggregate in the tool so Claude never touches the raw rows.
DIAGRAM Shrink before it enters context
(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
EXAM TRAPS
"...+920 more") so Claude knows the view is partial and can refine or paginate.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.