에이전트에게 updateUser와 deactivateUser라는 두 가지 도구를 주었습니다. 지원 티켓에는 “이 계정을 닫아주세요”라고 적혀 있었습니다. 에이전트는 deactivateUser를 호출했습니다. 지난주에는 거의 동일한 티켓이 updateUser를 status: "closed"로 호출하게 했고, 이는 API에서 허용되었으며 다운스트림에서 약간 다른 의미를 가졌습니다.
아무것도 고장 나지 않았습니다. 모델은 두 가지 그럴듯한 옵션 중에서 설명이 어떤 상황에 적용되는지 알려주지 않아 선택하고 있었습니다. 도구 선택은 사람들이 모델 탓으로 돌리고 스키마에서 수정하는 실패 모드입니다. 모델이 의존할 수 있는 유일한 것이 스키마이기 때문입니다.
이 가이드는 모델이 도구를 선택할 때 실제로 무엇을 읽는지, 구별되는 이름과 설명을 작성하는 방법, 매개변수 설계가 오류율을 어떻게 변경하는지, 그리고 문구 변경이 조용히 문제를 일으키지 않도록 선택을 테스트하는 방법을 다룹니다. OpenAPI 스펙을 에이전트 도구로 전환하는 가이드에서처럼 도구가 스펙에서 생성되면, 이는 스펙에 무엇이 포함되어야 하는지에 대한 질문이 됩니다.
Apidog은 도구가 API 정의에서 온다면 설명이 위치하는 곳이므로, 하나를 개선하면 문서와 도구가 함께 개선됩니다.
모델이 보는 것
선택의 순간에 모델은 대화, 시스템 프롬프트, 그리고 도구 정의 목록을 가지고 있습니다. 각 정의는 이름, 설명, 그리고 매개변수 스키마입니다. 모델은 API 문서, 코드 주석, 또는 updateUser가 레거시라는 부족 지식을 가지고 있지 않습니다.
이는 모든 모호성 해소가 정의 자체에 작성되어야 함을 의미합니다. OpenAI 함수 호출 가이드와 Anthropic 도구 사용 문서 모두 동일한 점을 지적합니다. 설명은 전체 정의에서 가장 중요한 텍스트이며, 간결하기보다는 장황해야 합니다.
선택 오류는 네 가지 형태로 나타나며, 각각 다른 수정 방법을 가집니다.
두 정의가 겹칠 때 모델이 유사한 도구를 선택합니다. 각 설명이 언제 사용하지 말아야 하는지를 명시하도록 수정하십시오. 어떤 설명도 작업 언어와 일치하지 않을 때 모델이 아무것도 선택하지 않고 기억에서 답변합니다. 사용자가 사용하는 단어를 사용하여 수정하십시오. 매개변수가 모호할 때 모델이 잘못된 인수로 올바른 도구를 선택합니다. 유형, 열거형, 단위를 사용하여 수정하십시오. 순서가 중요하고 아무것도 명시되지 않았을 때 모델이 도구들을 잘못 연결합니다. 설명에 전제 조건을 명시하여 수정하십시오.
도구의 기능에 따라 이름을 지정하세요
이름은 모델이 가장 먼저 읽기 때문에 길이보다 더 많은 신호를 전달합니다.
전체 도구 세트에서 verbNoun 스타일을 동일하게 사용하십시오: createOrder, refundOrder, getOrderStatus. order_create, getOrder, refund를 혼합하는 세트는 모든 이름을 약간 더 읽기 어렵게 만들므로 개별 선택만큼 일관성이 중요합니다.
객체에 대해 구체적으로 설명하십시오. search는 좋지 않은 도구 이름입니다. searchCustomersByEmail은 좋은 이름이며, 모델에게 무엇을 검색하는지 그리고 어떻게 검색하는지 모두 알려줍니다.
내부 용어를 피하십시오. API가 고객을 “entity”라고 부르고 구독을 “instrument”라고 부른다면, 모델은 그 단어들을 “customer”와 “plan”이라고 말하는 티켓과 연결하지 못할 것입니다. 스키마의 언어가 아니라 작업의 언어로 도구 이름을 지정하십시오.
여러 컨텍스트에서 이름을 재사용하지 마십시오. 다른 네임스페이스에 있는 list라는 두 개의 도구는 하나의 목록에 나타나는 순간 모호성으로 붕괴됩니다.
구분하는 설명을 작성하세요
유용한 설명은 네 가지 질문에 답합니다: 무엇을 하는지, 무엇을 변경하는지, 언제 사용해야 하는지, 그리고 언제 사용하지 말아야 하는지.
다음은 약한 쌍입니다:
{ "name": "updateUser", "description": "사용자를 업데이트합니다." }
{ "name": "deactivateUser", "description": "사용자를 비활성화합니다." }
그리고 실제로 구분되는 쌍입니다:
{
"name": "updateUser",
"description": "활성 사용자의 이름, 이메일, 시간대 등 프로필 필드를 업데이트합니다. 사용자 요청에 따른 수정 및 프로필 편집에 사용하세요. 계정 상태를 변경하지 않습니다. 계정을 비활성화하려면 deactivateUser를 사용하세요. 계정을 닫거나 취소하는 데 사용하지 마세요."
}
{
"name": "deactivateUser",
"description": "사용자 계정을 비활성화하여 모든 세션을 취소하고 로그인 차단합니다. reactivateUser로 되돌릴 수 있습니다. 고객이 계정을 닫거나, 취소하거나, 일시 중지하거나, 정지해달라고 요청할 때 사용하세요. 데이터를 삭제하지 않습니다. 영구 삭제를 위해서는 되돌릴 수 없는 deleteUser를 사용하세요."
}
네 가지 기술이 작동하고 있습니다.
형제 도구 이름을 명시하세요. "대신 deactivateUser를 사용하세요"는 모델이 이들을 비교하는 바로 그 순간에 모호성을 직접적으로 해결합니다.
사용자의 어휘를 포함하세요. "닫기", "취소", "일시 중지", "정지"와 같은 단어들은 티켓에 나타나는 단어들이기 때문에 포함되었습니다. 이는 가장 높은 효과를 가져다주는 편집이며, 거의 비용이 들지 않습니다.
무엇을 하지 않는지 명시하세요. 부정적인 진술은 긍정적인 진술보다 더 구별됩니다. 인접한 두 도구의 긍정적인 주장은 비슷하게 보이는 경향이 있기 때문입니다.
되돌릴 수 있는지 여부를 표시하세요. 위험이 있다고 말하면 모델은 위험에 대해 추론합니다. 이는 AI 에이전트 가드레일에 대한 게시물에 있는 강제 패턴과 짝을 이룹니다. 진정한 보호는 여기에 속합니다.
길이는 괜찮습니다. 파괴적인 엔드포인트에 대한 한 번의 잘못된 호출을 방지하는 백 단어 설명은 저렴합니다.
잘못된 인수를 어렵게 만들도록 매개변수를 설계하세요
올바른 도구가 선택되면 인수가 다음으로 잘못될 수 있는 부분입니다.
JSON Schema는 필요한 제약 조건의 대부분을 제공하며, JSON Schema 유효성 검사 어휘는 도구 호출 API가 지원하는 키워드를 빠르게 훑어볼 가치가 있습니다.
집합이 닫혀 있을 때는 언제든지 열거형을 사용하십시오. 문자열로 선언된 status 매개변수는 임의의 값을 초대합니다. 열거형으로 선언되면 API가 허용하는 값으로 모델을 제한합니다.
"status": {
"type": "string",
"enum": ["pending", "paid", "refunded", "cancelled"],
"description": "주문 상태입니다. 'cancelled'는 전혀 이행되지 않았음을 의미하고, 'refunded'는 이행 후 취소되었음을 의미합니다."
}
이름에 단위를 넣으세요. amount는 모호하며 모델이 달러 또는 센트를 불일치하게 추측할 것입니다. amount_cents는 결코 그렇지 않습니다. timeout_seconds, distance_meters, duration_ms도 마찬가지입니다.
날짜 형식에 예시를 제공하십시오. "description": "ISO 8601 형식의 시작 날짜입니다. 예: 2026-08-26"은 "시작 날짜"만 있는 것보다 훨씬 더 자주 올바르게 형식화된 날짜를 생성합니다.
필수 목록을 정직하게 유지하십시오. 모든 것을 선택 사항으로 표시하는 것은 런타임으로 오류를 밀어 넣고, API가 합리적으로 기본값을 지정하는 것을 필수라고 표시하는 것은 모델이 값을 발명하게 만듭니다. 둘 다 흔하며, 둘 다 에이전트를 위한 API 오류 설계에 대한 게시물에서 다룬 유효성 검사 오류로 나타납니다.
중첩된 것보다 평평한 것을 선호하십시오. {"customer": {"address": {"postal_code": "..."}}}를 채우는 모델은 customer_postal_code에서는 발생하지 않는 구조적 실수를 저지릅니다. 도구 경계에서 평탄화하고 실행기에서 재구성하십시오.
과부하된 도구를 분할하십시오. 다른 모든 필드의 의미를 변경하는 mode 매개변수가 있는 도구는 실제로 두 개의 도구입니다. 이를 분할하면 선택이 향상되고 두 스키마 모두 단순화됩니다.
전제 조건과 순서를 명시하세요
모델이 순서를 모르면 여러 단계로 구성된 작업이 실패합니다. 종속 도구의 설명에 명시하십시오:
{
"name": "captureCharge",
"description": "이전에 승인된 청구를 캡처합니다. authorizeCharge에서 받은 authorization_id가 필요합니다. 아직 가지고 있지 않다면 authorizeCharge를 먼저 호출하세요. 승인된 금액보다 많이 캡처할 수 없습니다."
}
두 줄만으로 모델이 이미 읽고 있는 곳에서 순서 문제가 처리됩니다. 이는 전체 클래스에 적용됩니다: 생성 후 업데이트, 처리 전 업로드, 캡처 전 승인. 종속 단계의 설명이 이전 단계를 명시하지 않으면 모델은 이를 건너뛸 것으로 예상하십시오. 순서가 여러 호출이 아닌 여러 에이전트에 걸쳐 있는 경우, 하위 에이전트 간 컨텍스트 전달에 대한 게시물에 있는 핸드오프 규칙이 적용됩니다.
다른 행동과 마찬가지로 선택을 테스트하세요
설명은 코드이며, 퇴행합니다. 누군가 스타일 가이드에 맞추기 위해 설명을 줄이면 에이전트는 다음 화요일에 잘못된 엔드포인트를 선택하기 시작합니다.
작은 선택 스위트를 구축하십시오. 20~50개의 프롬프트 각각에 예상하는 도구를 포함하십시오. 실행하고, 모델이 어떤 도구를 선택하는지 기록하며, 이름만으로 주장하십시오. 인수는 실행마다 다르지만, 선택은 달라져서는 안 됩니다. 이것은 비결정적 AI 에이전트 테스트에 대한 가이드의 실제적인 형태입니다.
다음과 같이 가장 깨지기 쉬운 경우로 시드를 심으십시오:
- 세트에서 가장 유사한 두 도구와, 각각으로 라우팅되어야 하는 프롬프트.
- API 어휘가 아닌 고객 어휘를 사용하는 프롬프트.
- 아무것도 일치해서는 안 되는 프롬프트로, 올바른 동작은 강제로 호출하는 대신 질문하는 것입니다.
- 잘못 선택하면 실제 비용이 발생하는 파괴적인 도구.
각 프롬프트를 여러 번 실행하십시오. 5번 중 4번 이기는 도구는 프로덕션에서 동전 던지기이며 설명 작업이 필요합니다.
선택 테스트가 라이브 데이터에 닿지 않도록 실행을 모크에 연결하십시오. 프로덕션 대신 모크에 대해 에이전트 실행에 대한 게시물은 설정을 다루며, Apidog은 도구가 생성된 동일한 정의에서 해당 모크를 제공할 수 있어 스키마와 동작을 일치시킵니다.
동일한 방식으로 잘못되는 세 가지 세트
CRUD 세트. API는 수년간 발전해 온 엔드포인트에서 생성된 getUser, listUsers, searchUsers, queryUsers를 노출합니다. 모델에게 이들은 하나의 아이디어에 대한 네 가지 이름입니다. 해결책은 이 네 가지에 더 나은 설명을 추가하는 것이 아니라, 그중 하나를 에이전트에 노출하고 나머지는 도구 목록에서 제외하는 것입니다. 큐레이션된 세트는 항상 완벽한 세트보다 낫습니다.
관리자 세트. 읽기 도구와 파괴적인 도구는 동일한 어조로 나란히 있습니다: getInvoice, voidInvoice, deleteInvoice. 텍스트에는 이들 중 두 가지가 경력을 망칠 수 있다는 신호가 없습니다. 설명에 결과를 추가하고, 승인용으로 표시하며, 문구를 신뢰하기보다는 실행기에서 강제를 유지하십시오. 계층화된 접근 방식은 에이전트가 API를 망가뜨리는 것을 막는 게시물에 있습니다.
레거시 세트. 두 개의 엔드포인트가 동일한 작업을 수행하며, 하나는 더 이상 사용되지 않습니다. 스펙에는 여전히 둘 다 나열되어 있으므로 제너레이터는 둘 다 생성하고, 에이전트는 절반 정도는 오래된 것을 선택합니다. 더 이상 사용되지 않는 작업을 생성된 도구에서 제거하거나, 해당 설명의 시작 부분에 "사용 중단됨. 대신 createOrderV2를 사용하십시오."라고 명시하십시오. 모델은 이 문구가 맨 앞에 있을 때는 존중하고, 맨 뒤에 묻혀 있을 때는 무시합니다.
설명은 공유 구성입니다
도구 설명이 동작을 이끈다는 것을 받아들이면, 다음 질문은 누가 그것들을 소유하는가입니다. 대부분의 팀에서 답은 우연히 정해집니다: 에이전트를 처음 설정한 사람이 자신의 컴퓨터에 있는 파일에서.
대신 도구 세트를 다른 인터페이스처럼 검토되는 공유 아티팩트로 취급하십시오. 에이전트 작업을 중심으로 구축된 플랫폼은 종종 이를 직접 모델링합니다. Sharkly Agent는 지침, 런타임, 기술, 저장소를 포괄하는 저장된 구성이며, 이를 스페이스에서 공유하면 한 사람의 작업 설정이 팀에서 재사용 가능해집니다. 가치는 저장소가 아닙니다. 설명 변경이 모든 사람에게 영향을 미치는 검토 가능한 편집이 되는 것이지, 한 개발자의 에이전트가 나머지 에이전트와 다르게 동작하게 만드는 조용한 로컬 조정이 아니라는 점입니다.
사용자가 가져오는 단어에 주목하세요
가장 흔한 차이는 어휘입니다. 당신의 API는 subscription이라고 말하지만, 고객들은 plan, membership, billing이라고 말합니다. 당신의 API는 deactivate라고 말하지만, 그들은 cancel, close, turn off라고 말합니다.
실제 언어를 수집하십시오. 지원 티켓, 검색 로그 또는 실패한 에이전트 실행 기록에서 주요 문구를 가져와서 일치해야 할 도구의 설명에 추가하십시오. 이는 한 시간 정도의 비용이 들지만, 대개 스키마 튜닝의 어떤 노력보다 선택 정확도를 더 많이 향상시킵니다.
실패에도 주의를 기울이십시오. 에이전트가 아무것도 선택하지 않고 자신의 지식에서 답변할 때, 그것은 추론 실패가 아니라 어휘 오류입니다. 작업 언어가 도구 텍스트와 겹치지 않았기 때문에 도구가 보이지 않았던 것입니다.
도구 세트를 위한 체크리스트
- 이름은 하나의
verbNoun규칙을 따르며 특정 객체를 명명합니다. - 모든 설명은 무엇이 변경되는지, 언제 사용해야 하는지, 언제 사용하지 말아야 하는지를 명시합니다.
- 겹치는 도구는 서로를 명시적으로 명명합니다.
- 설명에는 내부 용어뿐만 아니라 사용자가 실제로 사용하는 단어가 포함됩니다.
- 파괴적이고 돌이킬 수 없는 행동은 설명에 명시되어 있습니다.
- 모든 닫힌 세트에 대해 열거형이 선언됩니다.
- 단위와 형식은 매개변수 이름 또는 설명에 예시와 함께 포함됩니다.
- 필수 목록은 API가 실제로 강제하는 것과 일치합니다.
- 종속 도구는 전제 조건을 명명합니다.
- CI에서 모크를 대상으로 선택 스위트가 실행됩니다.
모델은 당신이 작성한 텍스트에 대해 패턴 매칭을 수행합니다. 잘못 선택하면 텍스트가 가장 먼저 찾아볼 곳이며, 보통 변경해야 할 유일한 곳입니다. 설명, 모크, 테스트를 하나의 프로젝트에서 원한다면 Apidog를 다운로드하십시오.
자주 묻는 질문
도구 설명은 얼마나 길어야 합니까? 모호성을 해소할 수 있을 만큼 길어야 하며, 일반적으로 두세 문장 정도입니다. 설명은 컨텍스트를 차지하므로 모호하지 않은 도구에 대한 설명은 줄이고, 서로 인접한 도구에 공간을 할애하십시오.
설명에 예시를 넣어야 합니까? 형식과 단위의 경우 예시를 넣으면 모든 종류의 오류를 제거할 수 있으므로 그렇습니다. 긴 사용 예시는 컨텍스트를 차지하고 선택에 거의 영향을 미치지 않으므로 건너뛰십시오.
많은 좁은 도구를 갖는 것이 좋습니까, 아니면 몇 개의 유연한 도구를 갖는 것이 좋습니까? 어느 정도까지는 좁은 도구가 좋습니다. 각 도구는 한 가지 일을 하기 때문에 더 안정적으로 선택됩니다. 수십 개를 넘어서면 목록 자체가 문제가 되어 필터링하거나 검색해야 합니다. 이는 OpenAPI에서 에이전트 도구 생성에 대한 게시물에서 다루었습니다.
대신 시스템 프롬프트에서 선택을 수정할 수 있습니까? 부분적으로 가능하며, 한두 가지 알려진 혼란에 대한 합리적인 임시방편입니다. 하지만 확장성이 떨어집니다. 프롬프트는 모든 도구에서 공유되는 반면 설명은 필요한 도구와 함께 이동하기 때문입니다.
모델이 계속 매개변수 값을 발명하면 어떻게 해야 합니까? 유형을 제한하고, 열거형을 추가하며, 값이 구성되는 것이 아니라 이전 호출에서 와야 한다고 설명에 명시하십시오. 그래도 발생하면 래퍼에서 유효성 검사를 수행하고 허용되는 값을 명시하는 오류를 반환하십시오.
이러한 규칙이 MCP 서버에도 적용됩니까? 네, 그렇습니다. MCP 서버는 동일한 형태로 이름, 설명, 스키마를 노출하므로 동일한 문구 규칙이 적용됩니다. MCP란 무엇인가에 대한 설명은 프로토콜 자체를 다룹니다.