주문 잘 적기

호출 LLM 이 실제로 부르는 주문 적기

tools: 의 각 항목은 호출 LLM (Claude, ChatGPT 등) 과의 계약서예요. LLM 은 name·description·inputSchema 를 읽고 "이 주문을 부를까", "어떤 인자를 넘길까" 를 결정해요. 이게 부실하면 LLM 이 불러야 할 때 안 부르거나, 부르더라도 이상한 인자로 호출합니다.

name

ASCII 식별자. 소문자 snake_case 권장. 첫 글자는 영문자, 그 뒤로 영문/숫자/언더바. 64자 이내. 같은 manifest 안에서 유일해야 함.

• ✅ get_rate, convert_currency, add_expense
• ❌ getRate (camelCase 는 긴 목록에서 한 단어로 읽혀 LLM 이 잘 못 고름), get-rate (하이픈 불가), 1st_tool (영문자 시작이어야 함)

description — 가장 중요한 필드

LLM 이 "부를지 말지" 결정할 때 읽는 글. 호출자 (LLM) 가 읽는다는 걸 생각하고 적어요. 세 가지를 담아주세요:

1. 무엇을 하는지 한 문장으로. 2. 언제 부르는지 — 어떤 사용자 발화나 상황에서 발동. 3. 무엇을 돌려주는지 — 자명하지 않으면.

한국어 OK; 호출 LLM 들 한국어 잘 알아들어요. 1~4000자. 단일 주문이면 두세 문장~여섯 문장이 적당, 복잡한 OCR 파이프라인 같은 거면 좀 더 길게.

yaml
- name: get_rate
  description: 두 통화 간 현재 환율을 돌려줌. 사용자가 "환율이 얼마야"라고 묻거나 환전을 고민할 때 부른다. 결과는 { rate: number } 형태.

vs.

yaml
- name: doStuff
  description: stuff

아래 쪽은 LLM 한테 아무것도 안 알려줘요 — 이러면 LLM 이 그냥 안 부르거나, 반대로 매 메시지마다 부르거나.

inputSchema

인자 없는 주문이면 통째로 생략. 적을 때는:

yaml
inputSchema:
  type: object               # 최상단은 항상 "object"
  properties:
    from:
      type: string
      description: ISO 4217 통화 코드. USD, KRW 같은 것.
    to:
      type: string
      description: 변환 대상 통화
  required: [from, to]

• 최상단은 항상 type: object. property 타입: string, integer, number, boolean, array, object, file.
• 각 property 에 description 꼭 — LLM 이 거기 무엇을 넣어야 할지 알 수 있게. 단위·형식·예시값까지.
• required: 는 꼭 있어야 하는 키 이름들. 거기 없는 건 다 선택.
• property 는 도구당 16개까지. 중첩은 한 단계만 (object 안의 object 는 OK, 더 깊이는 거부).

완성된 좋은 예시

yaml
- name: get_rate
  description: 두 통화 간 현재 환율을 돌려줌. 사용자가 "환율이 얼마야"라고 묻거나 환전을 고민할 때 부른다.
  inputSchema:
    type: object
    properties:
      from:
        type: string
        description: ISO 4217 통화 코드. USD, KRW, JPY 같은 것.
      to:
        type: string
        description: 변환 대상 통화 (ISO 4217)
    required: [from, to]

description 에 발동 트리거 (사용자 발화) 가 들어있고, property 마다 단위가 있고, required 로 호출 모양이 명확. LLM 에게 필요한 게 다 있어요.