지난 글까지 호출을 어떻게 실행하고 묶을지를 봤다. 그런데 실행 전에 결정되는 것이 하나 있다. 모델이 그 도구를 고를지, 인자를 어떻게 채울지는 전적으로 스키마에 적힌 텍스트만 보고 정해진다. 함수 본문이 얼마나 정확하든 모델은 그것을 볼 수 없다. 이 사실을 받아들이면 도구 스키마는 API 문서가 아니라 프롬프트의 일부라는 게 분명해진다.
이 글은 이름, 설명문, 인자 제약, 도구 개수, 반환값을 차례로 짚고, 끝에서 고친 스키마가 나아졌는지 재는 법을 본다.
모델이 읽는 텍스트
구현과 스키마
도구 하나는 두 부분으로 이루어진다. 실제로 일을 하는 함수 본문이 구현이고, 그 함수를 이름·설명문·인자 정의로 적어 모델에게 건네는 JSON 묶음이 도구 스키마다. 인자 정의는 대개 JSON Schema 문법을 따르므로 타입과 제약을 기계가 읽을 수 있는 꼴로 적는다. 모델은 이 둘 중 스키마만 받는다. 구현은 우리 서버에 있고, 모델이 호출을 내보낸 뒤에야 실행된다.
그러니 모델의 판단은 순서가 정해져 있다. 사용자 메시지를 읽고, 스키마 목록을 훑고, 그중 하나를 고르고, 설명문과 인자 정의를 보며 값을 채운다. 이 가운데 어느 단계에서도 함수 본문은 나오지 않는다. 구현이 날짜를 내부에서 한국 시간으로 바꿔 준다는 사실도, 주문번호가 들어오면 검색 대신 바로 조회로 빠지는 분기가 있다는 사실도 스키마에 안 적혀 있으면 모델에게는 없는 사실이다.
이 구조에서 나오는 결론이 이 글 전체의 전제다. 도구가 엉뚱하게 불리면 원인은 대개 구현이 아니라 스키마에 있다. 스키마는 모델이 읽는 텍스트이므로 프롬프트를 다듬듯 다듬는다.
고정분의 크기
스키마가 프롬프트라는 말에는 비용도 따라온다. 도구 목록은 요청마다 통째로 컨텍스트에 실린다. 컨텍스트는 모델이 한 번의 요청에서 읽는 텍스트 전부이고, 우리는 그 안의 토큰 수만큼 값을 치른다. 사용자가 무엇을 묻든 목록 전체가 같은 자리에 같은 크기로 들어가므로, 도구 목록은 요청마다 붙는 고정분이다.
크기를 어림해 보자. 설명문 두세 문장과 인자 서넛을 가진 도구 하나가 스키마로 대략 200~400토큰이다. 정확한 수는 토크나이저마다 다르지만 자릿수는 이 근처다. 도구가 25개면 가운데 값 300을 잡아 7,500토큰이 된다. 그런데 에이전트는 질문 하나에 모델을 한 번만 부르지 않는다. 도구를 부르고 결과를 받고 다시 판단하는 왕복이 질문 하나에 여섯 번 돈다면, 사용자 질문 하나가 도구 목록만으로 45,000토큰을 읽는 셈이다. 설명문에서 30토큰을 덜면 30에 왕복 수와 질문 수를 곱한 만큼이 덜린다.
옮겨 온 API 문서
가장 흔한 실수는 사내 API 문서를 그대로 스키마로 옮기는 것이다. API 문서는 사람 개발자를 위해 쓰였다. 인증 방식, 오류 코드 표, 페이지 나누기 규칙, 하위 호환을 위해 남겨 둔 인자까지 다 들어 있고, 사람은 그중 필요한 것만 골라 읽는다. 모델은 고르지 않고 다 읽는다.
그래서 옮긴 문서는 토큰만 쓰는 것이 아니라 판단도 흐린다. legacy_mode처럼 쓰지 말라고 남겨 둔 인자가 스키마에 있으면 모델은 그것을 쓸 수 있는 선택지로 읽는다. 스키마에 넣을 것은 모델이 이 도구를 고를지, 인자를 어떻게 채울지 정하는 데 필요한 것뿐이다.
도구 이름
이름과 후보
모델은 도구 목록을 훑을 때 이름을 먼저 본다. 설명문은 이름으로 후보를 좁힌 뒤에 읽는다. 그래서 이름 하나만 고쳐도 선택 정확도가 눈에 띄게 바뀐다.
이름이 나쁘면 좁히는 단계가 일을 못 한다. 목록에 search, lookup, find_items가 나란히 있으면 이름으로는 아무것도 걸러지지 않고, 모델은 세 설명문을 다 읽고 견줘야 한다. 설명문까지 비슷하면 그다음은 사실상 운이다. 반대로 이름이 대상을 말하면 사용자가 「주문」을 꺼낸 순간 후보가 order가 붙은 도구 몇 개로 줄어든다.
동사와 대상
좋은 이름은 동사 + 대상의 꼴이고, 대상이 구체적이다. 동사는 도구가 무엇을 하는지를, 대상은 무엇에 대해 하는지를 말한다. 둘 중 하나가 빠지면 이름이 후보를 좁히지 못한다.
| 나쁜 이름 | 왜 | 나은 이름 |
|---|---|---|
search |
무엇을 검색하는지 없다 | search_orders |
get_data |
대상도 동작도 모호하다 | get_customer_profile |
handler |
동사가 아니다 | cancel_subscription |
query_v2 |
버전은 모델에게 의미가 없다 | query_inventory |
do_refund_and_notify |
두 가지를 한다 | issue_refund + send_notice |
표의 나쁜 이름들은 빠진 것이 제각각이다. search는 대상이 없고, get_data는 대상이 너무 넓어 없는 것과 같고, handler는 동사가 없다. query_v2는 모델이 모르는 v1과의 관계로 이름 자리를 썼다. 이름에는 모델이 판단에 쓸 수 있는 낱말만 넣는다.
부작용과 분할
마지막 줄의 do_refund_and_notify는 이름 문제로 보이지만 실은 설계 문제다. 도구가 호출되었을 때 바깥 세계에 남기는 변화를 부작용이라 한다. 환불은 돈을 움직이고 알림은 고객에게 메시지를 보낸다. 두 부작용이 한 도구에 묶여 있으면 모델은 둘 중 하나만 필요한 상황에서도 그 도구를 부르거나, 부르기를 망설인다.
상황을 하나 그려 보자. 상담원이 「환불은 처리했는데 고객에게 안내 문자를 다시 보내 달라」고 한다. 알림만 보내는 도구가 없으니 모델에게 남은 길은 둘이다. 환불을 한 번 더 일으킬 위험을 안고 do_refund_and_notify를 부르거나, 할 수 없다고 답하거나. 어느 쪽도 옳지 않다. issue_refund와 send_notice로 나뉘어 있었다면 고민할 것이 없었다. 기준은 간단하다. 부작용이 다르면 도구를 나눈다. 읽기만 하는 도구와 무언가를 바꾸는 도구를 한 이름에 섞지 않는 것도 같은 원칙이다.
경계 설명문
빠진 경계
설명문에서 자주 빠지는 것은 기능이 아니라 경계다. 경계는 그 도구가 맡는 범위가 어디서 끝나는지, 곧 무엇을 못 하는지다. 무엇을 하는지는 대개 이름에서 짐작되지만, 무엇을 못 하는지는 적어 두지 않으면 알 방법이 없다.
경계가 빠진 설명문이 어떻게 틀린 선택으로 이어지는지 따라가 보자. search_orders의 설명문이 「주문을 검색한다」 한 줄이고, 옆에 track_shipment가 「배송을 조회한다」로 서 있다. 사용자가 「지난주에 산 운동화 어디쯤 왔어?」라고 묻는다. 이 질문에서 눈에 띄는 낱말은 「지난주」·「산」·「운동화」이고, 셋 다 주문 쪽이다. 배송 추적에 필요한 송장 번호는 질문에 없다. 모델은 search_orders를 고르고, 돌아온 주문 기록의 status: "shipped"를 보고 「발송되었습니다」라고 답한다. 사용자가 알고 싶던 현재 위치는 끝내 조회되지 않는다. 어느 도구도 틀리게 동작하지 않았는데 답은 틀렸다. search_orders가 배송 상태를 모른다는 한 문장이 없었던 탓이다.
같은 도구를 경계까지 적으면 이렇다.
{
"name": "search_orders",
"description": "주문 이력을 키워드로 검색한다. 최근 2년치만 들어 있고, 배송 추적 상태는 포함되지 않는다(그쪽은 track_shipment를 쓸 것). 주문번호를 이미 알고 있다면 이 도구 대신 lookup_order를 쓴다.",
"input_schema": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "상품명 또는 주문자명. 주문번호를 여기에 넣지 않는다."
},
"since": {
"type": "string",
"format": "date",
"description": "이 날짜 이후 주문만. YYYY-MM-DD. 사용자가 기간을 말하지 않았으면 생략한다."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": ["keyword"]
}
}
범위·제외·대안
위 설명문에 든 정보는 넷이다. 범위(최근 2년), 제외 항목(배송 상태), 대안 도구 둘. 범위는 이 도구가 볼 수 있는 데이터가 어디까지인지를, 제외는 이름에서 기대할 법한데 실제로는 없는 것을, 대안은 그럴 때 어디로 가야 하는지를 말한다. 셋이 한 짝이다. 제외만 적고 대안을 안 적으면 모델은 할 수 없다는 것만 알고 갈 곳을 모르며, 결국 그 도구를 그냥 부르거나 사용자에게 되묻는다.
앞의 운동화 질문에 이 설명문을 넣으면 흐름이 달라진다. 모델은 search_orders로 주문을 찾되, 배송 상태는 track_shipment에서 보라는 문장을 읽었으므로 찾은 주문의 송장 번호로 한 번 더 호출한다. 호출이 하나 늘었지만 그 하나가 실제 답이다.
상호 참조
넷 가운데 대안 도구를 가리키는 문장이 특히 잘 듣는다. 비슷한 도구가 여럿일 때 모델이 헤매는 이유는 각 도구가 자기 얘기만 하기 때문이다. search_orders는 검색을 잘한다고 말하고 lookup_order도 조회를 잘한다고 말하면, 둘 사이의 선은 어느 설명문에도 없다. 두 설명문이 서로를 이름으로 부르는 상호 참조를 넣으면 그 선이 생긴다.
상호 참조는 양쪽에 다 적어야 한다. search_orders가 「주문번호를 알면 lookup_order」라고 말해도 lookup_order가 「키워드로 찾을 때는 search_orders」라고 말하지 않으면, 선이 반쪽만 선다. 그리고 도구 이름이 바뀌면 상대편 설명문도 함께 고쳐야 한다. 없는 도구를 가리키는 설명문은 아무 문장도 없는 것보다 나쁘다.
선택 인자
인자 쪽도 마찬가지다. required에 없어 비워 두어도 되는 인자를 선택 인자라 하는데, 모델은 빈칸을 그냥 두기보다 그럴듯한 값으로 채우는 쪽으로 기운다. since의 「사용자가 기간을 말하지 않았으면 생략한다」는 한 줄이 없으면 모델은 오늘 날짜나 임의의 과거 날짜를 채워 넣는다. 오늘 날짜가 들어가면 결과가 비고, 한 달 전이 들어가면 그보다 오래된 주문이 조용히 빠진다.
그래서 선택 인자에는 언제 비우는지를 적는다. 비워도 된다는 사실을 명시해야 모델이 실제로 비운다. 꼭 필요한데 값을 모르면 지어내지 말고 사용자에게 물으라고 적는다.
제약 키워드
제약과 설명문
설명문은 토큰을 쓰고, 모델이 반드시 지킨다는 보장도 없다. 반면 JSON Schema의 제약 키워드, 곧 enum·minimum·pattern처럼 값의 꼴을 못 박는 키워드는 구조화 출력 경로에서 강제되는 경우가 많다. 강제되지 않는 경로에서도 모델은 자연어 문장보다 제약을 더 한결같이 따른다. 같은 내용이라면 제약 쪽에 넣는 편이 싸고 확실하다.
"status": {
"type": "string",
"enum": ["pending", "shipped", "delivered", "cancelled"]
}
이렇게 쓰면 "description": "상태는 pending, shipped, delivered, cancelled 중 하나입니다"가 통째로 필요 없어진다. 설명문으로 적으면 모델은 문장을 읽고 넷을 기억해 두었다가 맞춰야 하지만, enum으로 적으면 넷 밖의 값은 애초에 선택지가 아니다.
설명문과 제약의 대응
같은 요령으로 옮길 수 있는 것들이 있다.
| 설명문에 쓰던 말 | 옮길 곳 |
|---|---|
| "~ 중 하나" | enum |
| "1에서 50 사이" | minimum / maximum |
| "YYYY-MM-DD 형식" | format: "date" |
| "ORD-로 시작하는 8자리" | pattern |
| "비워도 됨" | required에서 빼기 |
| "기본값은 20" | default |
표의 마지막 두 줄도 반만 옮겨진다. required에서 빼도 언제 비우는지는 설명문에 남고, 기본값이 20이어도 「전부 보여 줘」에 50을 넣으라는 판단은 설명문의 몫이다.
설명문의 몫
설명문에는 제약으로 표현할 수 없는 것만 남긴다 — 값의 출처, 쓰지 말아야 할 상황, 다른 도구와의 관계. 값의 출처는 「이 ID는 search_orders 결과의 order_id에서 가져온다」 같은 문장이다. 모델이 ID를 지어내는 일을 막는 데 이만한 문장이 없다. 쓰지 말아야 할 상황과 다른 도구와의 관계는 앞 절의 경계와 상호 참조다. 이렇게 정리하면 스키마가 짧아지면서 오히려 정확해진다.
도구 개수
개수 구간
개수가 늘면 두 가지가 동시에 나빠진다. 토큰이 늘고, 비슷한 도구 사이의 혼동이 는다. 후자가 먼저 온다. 앞에서 센 7,500토큰은 감당할 만해도, 엇비슷한 이름 셋 사이의 오선택은 그보다 먼저 눈에 띈다.
경험적으로 갈리는 지점은 이렇다.
- 10개 이하 — 대체로 문제없다. 이름과 설명만 정리하면 된다.
- 10~30개 — 혼동이 보이기 시작한다. 이름의 접두사로 묶고(
order_*,ship_*), 겹치는 도구를 합치거나 경계 문장을 넣는다. - 30개 이상 — 목록을 그대로 다 주면 안 된다. 상황에 따라 부분집합만 노출한다.
구간의 경계는 정확한 수가 아니라 자릿수다. 같은 20개라도 결제·배송·회원·재고처럼 영역이 서로 다른 20개는 10개처럼 다룰 수 있고, 한 영역에 몰린 20개는 30개처럼 다뤄야 한다. 세야 할 것은 전체 개수보다 이름과 설명문이 서로 겹치는 도구의 수다.
묶기와 합치기
10~30개 구간의 첫 처방은 이름의 접두사로 묶는 것이다. order_search, order_lookup, order_cancel처럼 영역 이름을 앞에 두면 모델이 목록을 훑을 때 영역 단위로 먼저 걸러진다. 대상이 앞으로 나왔을 뿐 동사와 대상이 다 있으니 앞의 원칙과 어긋나지 않는다. 순서는 목록 전체에서 하나로 통일한다.
두 번째 처방은 합치기다. search_orders_by_date와 search_orders_by_keyword처럼 같은 일을 조건만 바꿔 하는 도구가 둘이면, 하나로 합치고 조건을 인자로 받는다. 모델이 고를 것이 도구 둘 사이에서 인자 하나의 값으로 옮겨 가는데, 앞 절에서 본 대로 인자는 enum과 선택 인자로 꼴을 못 박을 수 있으므로 고르기가 쉬워진다. 다만 부작용이 다른 둘은 합치지 않는다. 앞의 환불·알림과 같은 이유다.
단계별 노출
30개 이상에서 흔한 처리가 단계별 노출이다. 대화 초반에는 도구를 몇 개만 주고, 사용자의 의도가 정해지면 그 영역의 도구를 추가로 붙인다. 다른 방법은 도구를 계층으로 두는 것이다 — 상위 도구 하나가 영역을 고르고, 그 결과로 하위 도구 목록이 들어온다. 어느 쪽이든 공통점은 하나다. 한 번에 모델이 판단해야 할 선택지 수를 줄인다.
두 방법의 값은 왕복 하나다. 계층을 두면 영역을 고르는 호출이 한 번 끼므로 응답이 그만큼 늦어진다. 첫 단계에서 영역을 잘못 고르면 그 아래 도구가 아예 안 보이므로, 상위 도구의 설명문에는 영역마다 무엇이 들었는지를 적는다.
캐시와 목록 변경
여기서 주의할 것은 캐시다. 프롬프트 캐시는 요청 앞부분이 직전 요청과 글자까지 같을 때 그 부분의 계산 결과를 다시 써서 비용과 지연을 줄이는 장치다. 도구 목록은 프롬프트 앞쪽의 고정 부분이라 캐시가 가장 잘 듣는 자리인데, 대화 중간에 목록을 바꾸면 그 지점부터 캐시가 깨진다. 앞의 25개·7,500토큰 목록이 캐시에 걸려 있다가 단계별 노출로 도구 다섯이 더 붙으면, 그 요청에서는 바뀐 자리 뒤의 목록과 대화 이력까지 다시 계산된다.
그래서 도구를 동적으로 붙일 거라면 바뀌는 지점을 최대한 뒤로 두거나, 대화 시작 시점에 한 번만 정하는 편이 낫다. 한 번 바뀐 목록은 다음 요청부터 다시 캐시에 걸린다. 피해야 할 것은 턴마다 목록이 달라지는 설계다. 그러면 캐시가 아예 서지 않고, 앞에서 센 고정분을 매 왕복 제값으로 치른다.
반환값
이력에 남는 결과
입력 스키마만 다듬고 반환값을 방치하는 경우가 많은데, 모델이 다음 행동을 정하는 재료는 반환값이다. 도구가 돌려준 결과는 모델에게 다시 텍스트로 들어가 대화 이력의 한 줄이 되고, 그 대화가 이어지는 동안 매 요청마다 함께 실린다. 도구 목록이 처음부터 고정으로 실리는 비용이라면, 반환값은 호출할 때마다 쌓여 가는 비용이다. 입력 스키마에서 판단에 쓸 것만 남겼듯, 결과에도 다음 판단에 쓸 것만 남긴다.
필드 덜기
먼저 필요한 필드만 돌려준다. 내부 API 응답을 그대로 넘기면 모델이 안 쓰는 필드 수십 개가 매 호출마다 컨텍스트에 쌓인다. 주문 하나를 조회했는데 내부 응답에 창고 코드, 정산 배치 ID, 생성·수정 타임스탬프 여섯 개, 결제 대행사의 원본 응답까지 들어 있다면 한 건이 800토큰쯤 된다. 모델이 답에 쓰는 것은 상품명·금액·상태·주문일 정도라 100토큰이면 충분하다. 열 건을 검색해 돌려주면 그 차이가 7,000토큰이고, 이 결과가 이력에 남아 남은 왕복마다 다시 실린다.
필드를 덜어 내는 것은 토큰만의 문제도 아니다. 안 쓰는 필드는 모델에게 쓸 수 있는 정보로 보인다. 내부 상태 코드 st: 4가 결과에 섞여 있으면 모델이 그 뜻을 짐작해 답에 녹이기도 한다.
빈 결과
빈 결과에는 말을 붙인다. []만 돌려주면 모델은 이것이 「없음」인지 「조회 실패」인지 구별하지 못한다. {"results": [], "note": "조건에 맞는 주문이 없다. 기간을 넓히거나 키워드를 바꿔 볼 것"} 정도면 충분하다.
둘을 가르는 이유는 다음 행동이 다르기 때문이다. 없음이면 모델은 조건을 바꿔 다시 찾거나 사용자에게 없다고 알린다. 조회 실패면 같은 조건으로 한 번 더 부르거나 지금은 확인할 수 없다고 알린다. 빈 배열 하나로 둘을 뭉뚱그리면, 데이터베이스가 잠깐 끊긴 순간에도 모델은 「주문 내역이 없습니다」라고 단정한다. 실패는 오류 문장으로 돌려준다.
수정 검증
평가 질문
스키마 수정은 프롬프트 수정과 똑같이 취급해야 한다. 즉, 고치기 전후를 같은 입력으로 비교해야 한다. 최소한의 형태는 이렇다 — 도구를 써야 하는 질문 20개와 쓰면 안 되는 질문 20개를 모아 두고, 스키마를 고칠 때마다 같은 마흔 개를 돌린다.
쓰면 안 되는 질문이 중요하다. 「주문 취소하면 환불은 언제 돼?」는 주문을 조회할 것 없이 정책을 답하면 된다. 「주문」 같은 낱말이 들어 있는데 도구가 필요 없는 질문이야말로 경계 설명문이 제대로 서 있는지를 드러낸다.
선택률과 오선택률
스키마를 고칠 때마다 두 값을 함께 본다. 선택률은 써야 하는 질문 가운데 모델이 그 도구를 고른 비율이고, 오선택률은 쓰면 안 되는 질문 가운데 그 도구를 고른 비율이다. 앞의 것은 높을수록, 뒤의 것은 낮을수록 좋다.
둘을 같이 봐야 하는 이유가 있다. 설명문에 「적극적으로 사용하세요」를 넣으면 선택률은 오르지만 오선택률이 같이 오른다. 가령 고치기 전에 써야 할 20개 중 14개를 골랐고(70%) 안 써야 할 20개 중 2개를 골랐다면(10%), 그 문장을 넣은 뒤에는 19개(95%)와 9개(45%)가 되는 식이다. 선택률만 보면 25포인트 나아졌는데, 실제로는 불필요한 호출이 네 배 반으로 늘었다. 같은 날 그 문장 대신 경계 문장을 넣은 판이 17개(85%)와 1개(5%)였다면 고친 것은 그쪽이다.
수정 절차
절차로 적으면 이렇다.
- 질문 마흔 개를 고정해 두고 지금 스키마로 선택률과 오선택률을 잰다.
- 스키마를 한 군데만 고친다. 이름과 설명문을 한꺼번에 바꾸면 무엇이 들었는지 모른다.
- 같은 질문으로 다시 재고, 두 값이 함께 나아졌을 때만 남긴다.
- 틀린 선택이 나온 질문은 따로 모아 다음 수정의 근거로 쓴다.
모델의 답은 같은 입력에도 조금씩 흔들리므로 질문마다 몇 번씩 돌려 평균을 본다. 그리고 모델을 바꿀 때도 이 마흔 개를 다시 돌린다. 같은 스키마라도 모델이 바뀌면 읽는 방식이 달라진다.
도구 스키마는 코드베이스에서 가장 자주 방치되면서 가장 자주 읽히는 텍스트다. 호출이 이상할 때 프롬프트를 열기 전에 그 도구의 설명문부터 다시 읽어 볼 값어치가 있다. 그리고 앞에서 센 대로 스키마는 요청마다 컨텍스트에 실리는 여러 항목 가운데 하나일 뿐이다. 시스템 프롬프트, 대화 이력, 검색해 온 문서, 도구 결과가 같은 창을 나눠 쓴다. 다음 글은 그 창 전체를 예산으로 놓고, 항목마다 자라는 방식과 줄이는 방법을 나눠 본다.
읽어주셔서 감사합니다. 😊

