Tool Result: 작고, 구조적이고, 다음 행동이 보이게

~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

결과는 다음 관찰값이야

tool이 실행된 뒤 모델이 보는 건 우리가 돌려준 것뿐이야. 시끄러운 dump를 주면 다음 결정도 시끄러워진다. 선명한 observation을 주면 다음 결정이 나아진다.

결정에 필요한 형태로 요약해

좋은 결과는 호출이 성공했는지, 무엇이 바뀌었는지, 어떤 사실이 중요한지, 다음에 무엇을 할 수 있는지 알려준다. upstream API가 돌려준 모든 field를 다 넣지 않아.

큰 결과는 preview와 handle을 돌려줘. 모델이 필요한 상세 정보를 id로 다시 요청하게 해야지, 쓸지도 모르는 자료로 context window를 채우면 안 돼.

Error도 관찰값이다

에러를 generic failure text 뒤에 숨기지 마. structured error type, retry 가능 여부, recovery suggestion을 돌려줘. observation이 명확하면 모델은 꽤 자주 적응한다.

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
}

복구 가능한 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

아는 API의 raw search result JSON을 하나 떠올리고, 모델에게 줄 더 작은 result envelope을 설계해봐.

Hint

id, title, 짧은 snippet, confidence, next action만 남기고 장식용 metadata는 버려.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousTool Schema Design: 모델이 읽는 API Next →Common Production Tools: Files, Web, Code

이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

🔔 답글 알림 (로그인 필요)

로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.