Tool 정의는 너와 모델 사이의 contract 야. 그 contract 에서 가장 평가절하된 필드는 description — 이 tool 을 언제 왜 쓰는지 모델한테 말해주는 prose. 프로덕션 팀이 description 에는 투자 부족, 화려한 schema 에는 과투자 — 흔한 실수야. 모델은 description 을 읽어서 tool 을 고르지, 네 희망사항 읽어서 안 골라.
Schema 면에서, 모든 modern provider 는 JSON Schema 를 — 작은 사투리 차이로 — 말해. 항상 통하는 모양은: {"type": "object", "properties": {…}, "required": [...]} 에 각 property 가 자기 type 과 한 줄 description 을 들고 있는 거. 닫힌 집합엔 enum ("status": open|closed|in_progress 중 하나). 날짜와 이메일 같은 건 format — 대부분 provider 가 강제하진 않지만, 모델이 valid 한 출력 내도록 bias 줘.
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: format 과 edge case. "city name" 만 말고 — "city name in English; for cities with translations like 'Seoul' use the romanized form, not '서울'." 그게 가장 흔한 실패 모드를 막는 description.
- Required 는 진짜 required. 파라미터가 정답 위해 필수면, required 마크. Optional 은 절반은 빠져 — 모델이 안 물어. Required 는 빠지면 구조화된 재질문 발동.
Schema 디자인은 engineering 으로 위장한 글쓰기 문제야. Schema 가 맞다는 건, 네 codebase 처음 본 동료가 tool 정의 읽고 90% 정확도로 — 이 tool 이 뭘 하고 모델이 언제 고를지 — 예측할 수 있을 때야.