C.W.K.
Stream
Lesson 02 of 05 · published

Tool Results: Small, Structured, Actionable

~26 min · tool-results, context-budget, json

Level 0Observer
0 XP0/40 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

The result is the next observation

After a tool runs, the model sees only what you return. If you return a noisy dump, the next decision becomes noisy. If you return a crisp observation, the next decision improves.

Summarize for decision-making

A good result says whether the call succeeded, what changed, which facts matter, and what the model can do next. It does not include every field the upstream API returned.

For large results, return a preview plus handles. Let the model ask for details by id rather than filling the context window with material it may never use.

Errors are observations too

Do not hide errors behind generic failure text. Return structured error type, retryability, and a recovery suggestion. The model can often adapt if the observation is clear.

Code

Result envelope·json
{
  "ok": true,
  "summary": "Found 3 matching orders. One is delayed.",
  "items": [
    {"id": "ORD-1042", "status": "shipped", "eta": "2026-05-05"},
    {"id": "ORD-1039", "status": "delayed", "eta": "unknown"}
  ],
  "next_actions": ["read_order_detail", "offer_refund_policy"],
  "truncated": false
}
Recoverable error envelope·json
{
  "ok": false,
  "error_type": "rate_limit",
  "message": "Order API rate limit exceeded.",
  "retryable": true,
  "retry_after_seconds": 30,
  "safe_next_action": "Tell the user the lookup is temporarily delayed."
}

External links

Exercise

Take a raw search result JSON from any API you know and design a smaller result envelope for the model.
Hint
Keep ids, titles, short snippets, confidence, and next actions. Drop decorative metadata.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.