Tool Schema Design: 모델이 읽는 API

~30 min · tool-schema, json-schema, descriptions

Level 0Observer

0 XP0/40 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Tool schema는 이빨 달린 prompt야

tool description은 장식용 주석이 아니야. 모델이 행동할지 말지 결정할 때 읽는 interface야. 나쁜 description은 tool choice를 랜덤으로 만들고, 정확한 description은 모델의 지식을 제한된 행동으로 바꿔준다.

구현이 아니라 의도를 이름 붙여

`db_query`보다 `search_customer_orders`가 좋아. 모델은 내부 저장소 구조가 아니라 task intent를 보고 도구를 골라야 해.

각 parameter에는 어떤 값이 들어가는지, 기대 format이 뭔지, 흔한 함정이 뭔지 적어. id를 받으면 어떤 id인지 말하고, 날짜가 ISO format이면 그렇게 말해.

도구는 좁게

거대한 `do_anything` tool 하나는 permissioning이 불가능하고 모델에게 애매함을 너무 많이 준다. 좁은 도구 여러 개가 validation, logging, testing, approval 모두 쉽다.

Code

좋은 tool schema·json

{
  "name": "search_customer_orders",
  "description": "Search customer orders by public customer id or email. Use when a user asks about past purchases, delivery status, refunds, or order history. Does not modify orders. Returns at most 10 summarized orders.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer": {
        "type": "string",
        "description": "Public customer id or verified email address."
      },
      "status": {
        "type": "string",
        "enum": ["any", "paid", "shipped", "refunded"],
        "description": "Optional status filter. Use 'any' unless the user asks for a specific status."
      }
    },
    "required": ["customer"]
  }
}

External links

Exercise

search나 update처럼 애매한 tool 하나를 골라 좁은 tool 세 개로 쪼개고 description을 써봐.

Hint

read, propose, apply로 나누면 좋다. apply tool은 더 강한 권한이 필요해.

Progress

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

← 🔄 싱글 에이전트퀴즈 · 4 questions Next →Tool Result: 작고, 구조적이고, 다음 행동이 보이게

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

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

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

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