JSON Schema 가 Contract

Tool 정의는 너와 모델 사이의 contract 야. 그 contract 에서 가장 저평가된 필드가 description — 이 tool 을 언제 왜 쓰는지 모델한테 알려주는 문장이지. 프로덕션 팀이 흔히 저지르는 실수가 여기 있어. 화려한 schema 에는 공을 잔뜩 들이면서 description 은 대충 넘어가. 모델은 description 을 읽어서 tool 을 고르지, 네 희망사항 읽어서 안 골라.

Schema 쪽은 사정이 단순해. 요즘 provider 는 전부 JSON Schema 를 쓰고, 사투리 차이만 조금 있어. 어디서든 통하는 모양은 {"type": "object", "properties": {…}, "required": [...]} 에 property 마다 type 과 한 줄짜리 description 을 달아주는 거야. 값이 정해져 있으면 enum 을 써 ("status": open|closed|in_progress 중 하나). 날짜나 이메일처럼 모양이 있는 값에는 format. 대부분의 provider 가 이걸 강제하진 않지만, 모델이 제대로 된 값을 내놓는 쪽으로 기울여주긴 해.

어렵게 배운 description 규칙 세 개:

Tool description 은 '뭘 하는지' 가 아니라 '언제 쓰는지'. "Get current weather for a city" 는 그냥 정의야. "Use this when the user asks about today's weather, temperature, or whether it will rain in a named city" 는 contract 고.
파라미터 description 에는 형식과 함정을. "city name" 에서 멈추지 마 — "city name in English; for cities with translations like 'Seoul' use the romanized form, not '서울'." 이런 한 줄이 제일 흔한 실패를 막아줘.
Required 는 진짜로 required 인 것만. 정답을 내려면 꼭 있어야 하는 파라미터면 required 로 표시해. Optional 로 두면 모델은 절반쯤 그냥 비워두고 물어보지도 않아. Required 인데 빠지면 그때야 제대로 되물어보지.

Schema 설계는 engineering 으로 위장한 글쓰기 문제야. Schema 가 제대로 됐다는 건, 네 코드를 처음 보는 동료가 tool 정의만 읽고도 이 tool 이 뭘 하는지, 모델이 언제 이걸 고를지를 열에 아홉은 맞힐 수 있다는 뜻이야.

Code

Description 을 제대로 쓴 tool — Anthropic 모양·python

{
  "name": "search_orders",
  "description": (
    "Search the customer's order history. Use this when the user mentions "
    "an order, a tracking number, a refund, or asks 'where is my package'. "
    "Do NOT use this for product browsing — use search_catalog for that."
  ),
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The customer's account ID, exactly as it appears in the user's profile context."
      },
      "status": {
        "type": "string",
        "enum": ["pending", "shipped", "delivered", "returned"],
        "description": "Filter by status. Omit to search all statuses."
      },
      "since": {
        "type": "string",
        "format": "date",
        "description": "Earliest order date to consider, in YYYY-MM-DD format."
      }
    },
    "required": ["customer_id"]
  }
}

OpenAI Responses API — 같은 모양, 봉투만 조금 달라·python

tools = [{
    "type": "function",
    "name": "search_orders",
    "description": "...",
    "parameters": {
        "type": "object",
        "properties": { ... },
        "required": ["customer_id"]
    }
}]

Exercise

이미 코드에 쓰는 tool 하나 골라서 description 을 세 번 다시 써: '뭐 하는지', '언제 쓰는지', '언제 쓰지 말아야 하는지 (대신 뭘 쓸지)'. 같은 prompt 로 모델한테 세 버전 다 돌리고 선택 정확도 봐. '언제 쓰는지' 가 보통 이기고, '언제 쓰지 말아야 하는지' 는 겹치는 tool 들 사이에서 승부를 갈라줘.

Code

External links

Exercise

Progress

댓글 0