코드는 정상인데 AI는 엉뚱한 도구를 부른다: Tool Calling 설계의 함정

 

API는 정상이다. 같은 함수에 같은 형식의 인자를 넣으면 서버는 기대한 결과를 반환한다. 그런데 AI 에이전트에 연결하면 비슷한 이름의 다른 도구를 고르고, 불필요한 목록을 전부 읽고, 이미 아는 식별자를 다시 추측한다. 이런 상황에서 시스템 프롬프트에 “정확하게 도구를 사용하라”를 한 줄 추가하는 것으로 문제가 끝날까.

 

AI 에이전트의 Tool Calling은 기존 API 연동과 닮았지만 같은 문제는 아니다. 사람이 작성한 코드는 어떤 함수를 어떤 순서로 호출할지 명시한다. 에이전트에서는 모델이 사용자 요청과 도구 설명, 이전 결과를 보고 다음 호출을 선택하는 구간이 생긴다. 함수 구현이 올바르다는 사실과 모델이 그 함수를 올바르게 선택하고 해석한다는 사실을 분리해서 봐야 한다.

 

이 글은 AI 에이전트의 도구 설계, Function Calling, 입력 스키마, 출력 형식과 오류 복구를 연결해 설명한다. Anthropic의 도구 작성 가이드와 OpenAI Function calling 공식 문서, 카카오페이와 ManyCoreSoft의 한국어 기술 글을 비교했다. 자료 확인 기준일은 2026년 10월 29일이다. 아래의 배송 상담 도구는 설명을 위한 가상 설계이며 실제 서비스에서 측정한 성능 보고서가 아니다.

 

핵심은 도구 수를 무조건 줄이거나 설명문을 무조건 길게 쓰자는 것이 아니다. 에이전트가 판단할 선택의 경계를 명확히 하고, 코드가 이미 알고 있는 사실을 다시 추측시키지 않으며, 도구 결과로 다음 행동을 정할 수 있게 하자는 것이다. 잘 만든 API도 에이전트에게는 사용하기 어려운 도구가 될 수 있다.

모델이 도구를 고르는 일과 서버가 실행하는 일은 다르다

Function Calling 또는 Tool Calling에서 모델은 도구의 이름과 인자를 포함하는 호출 요청을 생성한다. 애플리케이션은 이를 받아 실제 함수나 외부 API를 실행하고 결과를 다시 전달한다. 이후 모델은 결과를 바탕으로 답변하거나 다른 호출을 제안할 수 있다. 모델 출력과 실제 실행 사이에는 애플리케이션이 책임지는 단계가 있다.

 

OpenAI 공식 문서도 도구 정의 전달, 호출 수신, 애플리케이션 측 실행, 결과 전달, 최종 응답 또는 추가 호출의 흐름을 설명한다. 여기서 호출 요청을 받았다는 사실은 곧 실행해도 된다는 뜻이 아니다. 허용된 도구인지, 인자의 의미와 업무 규칙이 맞는지, 현재 사용자에게 권한이 있는지는 실행 계층에서 확인해야 한다.

 

도구가 설명된다는 사실과 사용 가능하다는 사실도 구분하자. 모델의 선택 범위를 제한하는 설정은 도움이 되지만 외부 시스템의 권한 통제를 대신하지 않는다. 숨겨 둔 도구를 호출하려는 출력이 오거나 예상하지 못한 이름이 들어오면 실행기가 거부할 수 있어야 한다. 정의를 잘 썼다는 이유로 서버 검증을 생략해서는 안 된다.

 

실패 위치는 적어도 몇 가지로 나뉜다. 도구를 써야 하는데 답만 했을 수 있고, 다른 도구를 골랐을 수 있으며, 맞는 도구에 잘못된 인자를 넣었을 수 있다. 호출이 정확했어도 결과를 오독하거나 실행 완료를 확인하지 않았을 수 있다. 마지막 답변 하나만 보고 모두 모델 지능의 문제로 처리하면 개선 지점을 놓친다.

이 구분은 책임 분리에도 유용하다. 모델에는 선택과 언어 해석을 맡기고, 애플리케이션에는 검증과 권한 및 외부 실행을 맡길 수 있다. 도구 제공자는 입출력과 실패 의미를 명확하게 정한다. 실제 제품에서는 역할이 더 복잡할 수 있지만, 어떤 단계가 무엇을 보장하는지 설명할 수 있어야 운영이 가능하다.

API 엔드포인트를 모두 도구로 만들 필요는 없다

기존 서비스에 API가 100개 있다고 해서 에이전트에게도 도구 100개를 그대로 노출해야 하는 것은 아니다. API는 서비스 내부의 자원 구조와 개발자 요구에 따라 나뉘었을 수 있다. 반면 에이전트는 사용자의 업무를 해결할 행동 단위를 선택해야 한다. 두 경계가 항상 일치하지는 않는다.

 

Anthropic은 모든 기존 기능을 그대로 감싸는 도구보다 실제 중요한 업무 흐름에 맞춘 도구부터 설계하라고 안내한다. 예를 들어 연락처 전체를 반환해 모델이 하나씩 읽게 하는 대신 필요한 연락처를 검색하는 도구를 제공할 수 있다. 처리 능력이 충분한 서버에서 할 필터링을 모델의 문맥과 추론에 떠넘길 이유는 없다.

 

배송 상담에서도 사용자 조회, 주문 목록, 배송 이벤트, 상품 메모를 각각 읽게 하는 것이 유일한 설계는 아니다. 읽기 전용으로 필요한 상태를 모아 주는 조회 도구를 검토할 수 있다. 다만 어떤 자료를 어떤 기준으로 모았는지와 빠진 범위는 알려 줘야 한다. 편의상 합쳤다는 이유로 정보의 의미를 숨기면 다른 형태의 오류가 생긴다.

 

반대로 모든 것을 하나의 만능 도구에 넣는 방식도 부담이 크다. 조회, 주소 변경, 취소와 고객 메시지 발송을 하나의 동작 값으로 처리하면 선택지가 함수 안으로 이동할 뿐 사라지지 않는다. 실행 영향이 다른 작업의 경계가 흐려지고, 실패 원인과 권한을 나누기도 어려워질 수 있다.

 

도구의 적절한 크기는 실제 요청과 실행 기록에서 찾아야 한다. 항상 함께 호출되는 읽기 작업을 묶을 수 있지만, 다른 조건에서 독립적으로 쓰이는 기능은 분리할 가치가 있다. 기능을 합쳐 호출 수가 줄었다면 결과를 이해하는 부담과 검증 범위가 늘지는 않았는지도 살펴보자. 도구의 개수만으로 품질을 판단하지 않는 것이 중요하다.

이름과 설명은 에이전트가 읽는 사용자 인터페이스다

사람이 버튼의 이름과 안내문을 보고 기능을 고르듯, 모델은 도구 이름과 설명을 중요한 단서로 사용한다. process, handle, run 같은 이름만으로는 어떤 대상에 어떤 효과를 내는지 알기 어렵다. 도구를 만든 개발자에게 당연한 구분이 모델에게도 당연하다고 가정해서는 안 된다.

 

search_customer와 search_order처럼 자원 경계가 드러나는 이름은 용도를 설명하는 데 도움이 될 수 있다. 여러 시스템의 검색이 동시에 있다면 billing_search와 support_search처럼 이름 공간을 구분할 수도 있다. 다만 특정 접두사 규칙이 모든 모델에서 최선이라는 보장은 없다. Anthropic도 이름 구성의 효과를 자체 평가로 확인하라고 설명한다.

 

설명에는 무엇을 하는지뿐 아니라 언제 사용하고 언제 사용하지 않는지 담을 수 있다. “주문 상태를 조회한다”에 그치지 않고 “현재 배송 상태와 마지막 갱신 시점을 반환하며 주소를 변경하지 않는다”라고 적으면 읽기와 변경의 경계를 알기 쉽다. 실제 구현도 설명과 일치해야 하며, 설명문이 부작용을 감추는 수단이 되어서는 안 된다.

입력의 출처도 알려 주자. user가 사용자 이름인지 계정 ID인지 모호하면 모델이 자연어 이름을 넣을 수 있다. customer_id라는 이름과 “인증된 고객 문맥 또는 조회 결과에서 얻은 식별자”라는 설명은 구분을 돕는다. 다만 설명을 썼다고 권한 검증이 완성되는 것은 아니다. 출처를 추측한 값을 서버가 그대로 믿지 않도록 해야 한다.

 

설명을 늘릴 때는 반복되는 실패와 연결하는 편이 좋다. 날짜 범위를 계속 오해한다면 경계 포함 여부와 시간대를 명시하고, 비슷한 도구를 혼동한다면 차이를 설명한다. 모든 가능한 예외를 미리 길게 나열하면 중요한 조건이 묻힐 수 있다. 예시를 추가한 효과도 모델과 과제에 따라 평가해야 한다.

입력 스키마에서는 불가능한 조합부터 줄이자

입력 스키마는 필요한 필드와 자료형을 정하는 장치다. 문자열 하나에 여러 의미를 숨기는 대신 명확한 필드와 제한된 선택지를 사용하면 형식적 오류를 줄이는 데 도움이 된다. 그러나 스키마가 보장하는 범위와 업무의 의미를 구분해야 한다. 문법이 맞는 주문 번호가 실제로 해당 고객의 주문이라는 보장은 없다.

 

예를 들어 mode라는 문자열에 임의의 값을 넣게 하는 대신 지원하는 동작을 열거할 수 있다. 서로 모순되는 on과 off를 동시에 받는 구조보다 하나의 상태 필드가 더 명확할 수 있다. 선택 사항과 필수 사항, 빈 문자열과 값 부재를 어떻게 처리할지도 정해야 한다. 스키마와 실행 코드의 기본값이 다르면 예상하지 못한 동작이 생긴다.

 

OpenAI 공식 문서의 strict 모드는 호출이 지원하는 스키마 형식을 따르도록 하는 기능이다. 문서는 객체의 추가 필드 제한과 필수 필드 등 요구 조건을 설명한다. 이 요구와 기본 동작은 API와 버전에 따라 확인해야 한다. 예전 예제를 복사하면서 현재 기본값까지 같다고 가정하지 않는 편이 좋다.

 

strict가 적용되더라도 잘못된 고객 ID나 틀린 날짜를 구조적으로 올바르게 출력할 수 있다. 형식 검증은 의미 검증을 대신하지 않는다. 금액 범위와 상태 전이, 대상 소유권, 이미 처리된 작업인지 같은 규칙은 별도로 확인해야 한다. “JSON이 맞다”와 “실행해도 맞다”를 다른 단계로 보는 이유다.

 

날짜와 단위도 구체화하자. 배송 조회의 날짜가 주문일인지 출고일인지, 종료 경계가 포함되는지, 시간대가 무엇인지 분명해야 한다. 숫자 필드가 수량인지 금액인지와 단위를 이름이나 설명으로 드러낼 수 있다. 한국어 요청을 해석하는 모델이 코드의 숨은 관례까지 자동으로 알아낼 것이라고 기대하지 말자.

모델이 추측하지 않아도 되는 값은 실행 계층에서 넣는다

로그인한 사용자의 계정이나 조직, 이미 선택된 주문은 애플리케이션이 알고 있을 수 있다. 이런 값을 매번 모델이 인자로 생성하게 하면 불필요한 선택과 오류 가능성이 생긴다. OpenAI 공식 가이드도 코드가 이미 아는 인자를 모델이 채우게 하지 않는 방법을 권한다. 실행 문맥에서 확정된 값을 사용하면 호출 표면을 단순하게 만들 수 있다.

 

다만 인자를 줄인다는 이유로 숨은 전제가 늘어서는 안 된다. 현재 어떤 주문이 선택되어 있는지 모델과 사용자가 이해할 수 있어야 한다. 문맥에 여러 주문이 섞였는데 “현재 주문”이 조용히 바뀌면 명시적 ID를 받는 구조보다 오히려 모호해질 수 있다. 선택된 대상의 수명과 변경 조건을 정해야 한다.

인증 정보는 특히 모델이 생성하는 값으로 취급하지 않는 편이 좋다. 접근 토큰이나 비밀키를 프롬프트에 넣어 호출 인자로 되돌려 받는 대신 실행 계층이 관리할 수 있다. 모델이 작업을 제안하는 역할과 서버가 인증된 사용자 문맥으로 실행하는 역할을 분리하는 것이다. 도구 정의가 간단해지는 것과 데이터 보호가 연결되는 지점이다.

 

자연어 이름과 기술 식별자도 각자 역할이 있다. 사람이 읽을 이름은 대상을 구별하는 데 도움이 되고 안정적인 ID는 후속 실행에 필요할 수 있다. 이름만 남기면 동명이인이나 이름 변경을 처리하기 어렵고, 의미 없는 ID만 주면 모델이 맥락을 이해하기 어렵다. 필요한 의미와 실행 식별자를 함께 제공하는 방법을 검토하자.

 

또한 출력에서 받은 식별자를 다음 호출로 전달할 때 유효 범위를 유지해야 한다. 다른 고객이나 다른 세션에서 얻은 ID를 잘못 재사용하지 않도록 한다. 도구가 같은 형식을 받는다고 모든 식별자가 서로 호환되는 것은 아니다. 자원 종류와 소유권을 실행 단계에서 확인할 수 있어야 한다.

출력은 많이 주는 것보다 다음 판단에 충분해야 한다

도구 응답이 크면 모델이 더 많은 정보를 갖게 되지만 중요한 단서를 찾기는 어려워질 수 있다. 사용자가 배송 상태를 물었는데 고객의 모든 주문과 내부 이벤트, 이미지 주소와 원시 메타데이터를 반환하면 문맥을 낭비할 수 있다. 필요한 것은 다음 판단과 답변에 충분한 정보다.

 

예를 들어 배송 상태, 마지막 이벤트 시각, 조회 기준 시각, 해당 배송의 식별자, 추가 조회 가능 여부를 반환하는 구성을 생각할 수 있다. 사용자가 물은 조건을 판단하는 데 예외 사유가 중요하면 그 정보도 필요하다. 짧게 만들기 위해 지연이나 누락을 감추면 안 된다. 관련성 높은 요약과 판단에 필요한 제한 사항을 함께 남겨야 한다.

 

Anthropic 가이드는 concise와 detailed처럼 응답 상세도를 선택하는 방식도 소개한다. 간단한 요약으로 판단하다가 후속 호출에 식별자나 세부 정보가 필요하면 상세 결과를 가져오는 것이다. 단, 모든 환경에서 이중 조회가 효율적인 것은 아니다. 실제 업무에서 추가 호출과 읽는 양의 균형을 평가해야 한다.

 

응답 형식도 JSON이 언제나 최고이거나 마크다운이 언제나 낫다고 단정할 수 없다. 정해진 필드의 상태와 식별자를 다루는 부분에는 구조화된 형식이 유용하고, 긴 문서 내용에는 읽기 쉬운 형식이 나을 수 있다. 형식 이름보다 내용과 경계, 누락 여부를 일관되게 이해할 수 있는지가 중요하다.

 

같은 success라는 값에도 의미를 명확히 하자. 요청이 접수되었는지, 실제 작업이 완료되었는지, 상태를 확인했는지는 다르다. 출력이 “완료”라고만 적히면 모델이 외부 처리가 끝났다고 보고할 수 있다. 도구가 보장하는 사실과 아직 확인되지 않은 상태를 구분해서 반환해야 한다.

오류 응답은 실패 통보이면서 복구 인터페이스다

도구가 오류 코드와 긴 스택 추적만 반환하면 모델이 다음에 무엇을 해야 할지 알기 어렵다. 반대로 무조건 “다시 시도하세요”라고 하면 같은 잘못된 호출을 반복할 수 있다. 오류 응답에는 실패의 종류와 수정 가능한 조건, 재시도 가능 여부를 담는 방법을 검토할 수 있다.

예를 들어 날짜 형식이 잘못되었다면 요구 형식과 잘못된 필드를 알려 준다. 검색 대상이 모호하다면 후보를 구분할 단서를 제공할 수 있다. 권한이 없다면 다른 경로로 같은 정보를 가져오라고 유도해서는 안 된다. 입력 수정으로 해결할 수 있는 문제와 허용되지 않은 행동을 구분해야 한다.

 

빈 결과도 중요한 상태다. 검색에 맞는 자료가 없다는 것과 서버가 조회에 실패했다는 것은 다르다. 목록이 비었다는 이유만으로 주문이 없다고 단정하면 도구 장애를 업무 사실로 바꿀 수 있다. 결과 없음, 접근 제한, 일부 실패, 시간 초과 같은 상태를 구별해서 모델과 운영자가 해석할 수 있게 하자.

 

오류 설명에 민감 정보가 섞이지 않도록 하는 것도 필요하다. 내부 연결 문자열이나 인증 정보, 전체 쿼리와 고객 원문을 그대로 반환하면 모델 문맥과 로그에 퍼질 수 있다. 복구에 필요한 최소 정보와 지원팀이 조사할 수 있는 안전한 참조를 나누는 방법을 고려할 수 있다.

 

실행 결과를 알 수 없는 변경 요청은 특히 주의해야 한다. 시간 초과가 발생해도 외부 작업은 이미 수행되었을 수 있다. 이때 결과 확인 없이 같은 변경을 반복하게 만드는 오류 메시지는 위험하다. 상태 조회가 가능한지와 어떤 조건에서 재시도할 수 있는지를 설계하고 실행 기록과 연결해야 한다.

검색과 페이지네이션은 도구 사용 전략을 바꾼다

전체 데이터를 나열하는 도구는 단순해 보이지만 에이전트에게 큰 탐색 부담을 줄 수 있다. 서버가 빠르게 필터링할 수 있는 조건을 모델이 긴 출력에서 하나씩 찾게 되면 토큰과 지연이 늘어난다. 검색, 기간 범위, 정렬과 제한 같은 기능을 도구에 넣는 것이 단순한 성능 옵션을 넘어 사용 전략을 바꿀 수 있다.

 

검색 필드의 의미는 명확해야 한다. query 하나가 전문 검색인지 정확한 코드 검색인지, 여러 조건을 어떻게 해석하는지 알려 줘야 한다. 모든 조건을 자유 텍스트 하나에 넣는 방식이 편할 때도 있지만 날짜와 상태처럼 구조적으로 제한할 수 있는 조건은 별도 필드가 더 명확할 수 있다. 어느 쪽이 좋은지는 실제 질의군으로 비교한다.

 

페이지네이션에서는 더 읽을 결과가 있는지와 다음 요청 방법을 알려 줘야 한다. 일부만 반환하고 조용히 끝내면 모델은 전체 결과라고 생각할 수 있다. 다음 커서나 전체 범위에 관한 정보를 제공하되, 커서가 어떤 검색 조건에 속하는지도 유지해야 한다. 다른 질의의 커서를 재사용하면 결과 해석이 틀어질 수 있다.

 

출력 제한으로 잘랐다면 잘렸다는 사실을 알리자. 관련 조건을 좁히거나 필요한 구간을 요청하도록 복구 경로를 제공할 수 있다. 긴 문서를 중간에서 자르고 예외 조항을 놓친 상태로 답하게 하는 것보다, 남은 범위와 조회 방법을 명시하는 편이 낫다. 반환 길이 최적화가 의미 보존을 해치지 않는지 확인해야 한다.

 

필터와 기본값은 반복 호출의 형태에도 영향을 준다. 기본 반환량이 너무 작으면 같은 요청이 여러 페이지로 늘고, 너무 크면 불필요한 내용을 계속 읽게 된다. 호출 수, 반환 토큰, 정답에 필요한 자료의 포함 여부를 함께 측정하자. 도구 호출 하나가 줄었다는 사실만으로 전체 효율이 좋아졌다고 판단하지 말자.

도구를 합칠 때 읽기와 변경의 경계를 지켜야 한다

여러 단계를 한 도구에 묶으면 모델의 부담을 줄일 수 있다. 그러나 조회 도구가 몰래 일정을 만들거나 상태를 바꾸면 설명과 실제 효과가 달라진다. 사용자가 상태를 물었을 뿐인데 변경이 일어난다면 호출 수를 줄였다는 이점보다 큰 문제가 된다. 기능 통합은 부작용을 숨기는 방식이 되어서는 안 된다.

 

업무를 묶을 때는 읽기 작업끼리의 통합과 변경 작업의 통합을 다르게 보자. 관련 문서를 모으는 조회는 하나로 묶기 쉬울 수 있지만, 조회 후 주소를 바꾸는 절차에는 별도의 조건과 권한 확인이 필요할 수 있다. 이미 허용된 범위에서 실행할 수 있는지와 새 판단이 필요한지를 구분해야 한다.

 

변경 도구의 응답에는 실제로 수행한 내용과 결과를 확인할 수 있는 정보가 필요하다. 계획만 만들었는지, 실행 요청이 접수되었는지, 최종 반영까지 확인했는지 드러내야 한다. 모델이 완료 문장을 만들기 전에 어떤 사실을 근거로 삼는지 명확해진다. 도구가 설명보다 넓은 효과를 내지 않도록 계약을 유지하는 것이 중요하다.

 

읽기 전용이나 변경 여부에 대한 메타데이터와 설명은 선택을 돕는 단서다. 그러나 그 표시 자체가 보안 경계는 아니다. 실제 실행기에서 사용자와 자원에 대한 권한을 확인해야 한다. 설명문에 적혀 있다는 사실만으로 잘못된 호출이 물리적으로 불가능해지는 것은 아니다.

 

따라서 도구 통합은 호출 수뿐 아니라 권한, 검증, 장애 복구 단위까지 고려하는 설계다. 너무 잘게 나누면 조합 부담이 커지고 너무 크게 묶으면 영향과 실패의 경계가 흐려진다. 대표 업무를 실행해 보고 사람이 이해할 수 있는 단위인지, 오류가 생겼을 때 어느 단계인지 찾을 수 있는지 확인하자.

많은 도구를 다루려면 선택과 호출을 따로 평가하자

도구가 많아지면 기능의 겹침과 설명 길이가 함께 늘어날 수 있다. OpenAI 공식 가이드는 처음 노출하는 함수 수를 작게 유지하고 실제 평가를 하도록 권한다. 문서의 숫자 권고는 보편적인 최적값이나 강제 한도로 읽지 않는 편이 좋다. 모델과 작업, 도구 간 유사성에 따라 선택 난도가 달라진다.

 

필요한 도구를 검색해 나중에 불러오는 방식도 가능하다. 다만 후보를 찾는 단계에서 필요한 도구를 놓치면 호출 단계가 아무리 좋아도 업무를 해결하기 어렵다. 도구 검색이 관련 후보를 포함했는지와, 후보가 주어졌을 때 적절히 호출했는지를 나눠 평가해야 한다.

 

카탈로그의 설명과 실제 함수 설명도 역할이 다를 수 있다. 앞단의 짧은 설명은 무엇을 불러올지 결정하게 돕고, 로딩된 명세는 인자를 어떻게 채울지 알려 준다. 앞단 설명이 너무 넓으면 필요 없는 도구를 불러오고, 너무 좁으면 관련 기능을 놓칠 수 있다. 두 단계를 모두 테스트해야 한다.

 

설정을 통해 특정 도구를 강제하는 경우도 있다. 이때 선택 정확도가 높아진 것처럼 보여도 실제로는 모델이 선택할 필요가 없어진 것일 수 있다. 업무 절차상 도구가 이미 정해져 있다면 합리적인 구성일 수 있지만, 자율 선택 능력의 개선과 구분해서 보고해야 한다. 평가가 무엇을 측정했는지 분명히 해야 한다.

 

도구를 찾지 못했을 때의 행동도 정해야 한다. 없는 함수를 지어내거나 비슷한 이름의 변경 도구로 대체하지 않게 해야 한다. 제공된 기능 안에서 해결할 수 있는 범위와 부족한 기능을 구분하도록 한다. 관련 없는 도구를 억지로 사용하는 것보다 가능한 대안을 안내하는 것이 올바른 결과일 수 있다.

배송 상담 에이전트의 도구를 다시 나누는 예시

가상의 배송 상담 에이전트에 get_user, list_orders, get_order, list_events, update_order 같은 도구가 있다고 하자. 이름만 보면 get_user가 누구를 조회하는지, update_order가 주소와 상태를 모두 바꾸는지 알기 어렵다. 모델이 이를 사용해 “내 주문은 언제 도착하나요?”라는 요청을 해결하도록 하면 불필요한 탐색과 잘못된 변경의 여지가 생긴다.

 

먼저 인증된 사용자 문맥은 서버에서 연결하고, 주문 검색과 배송 요약 조회의 입력을 명확히 정할 수 있다. 주문이 여러 개라면 날짜나 상품으로 후보를 좁힐 수 있게 하고 동명이인 같은 이름에 의존하지 않는다. 사용자에게 필요한 선택이 무엇인지와 도구가 이미 아는 대상을 구분하는 단계다.

 

배송 요약에는 현재 상태와 마지막 이벤트, 갱신 시점, 예상 일정의 출처와 확인 범위를 넣을 수 있다. 예상 일정이 제공되지 않는다면 값을 만들어 채우지 않고 미확인으로 표시한다. 상세 이벤트가 필요할 때만 추가로 읽게 할 수 있다. 요약 도구가 모든 배송 문제의 원인을 자동으로 확정한다고 설명해서는 안 된다.

 

주소 변경은 배송 조회와 구분한다. 현재 단계에서 변경이 가능한지, 필요한 입력이 무엇인지, 어떤 범위가 사용자 요청으로 허용되었는지 확인한다. 실제 변경이 있었다면 새 주소의 반영 상태를 확인할 수 있는 결과를 돌려준다. 이 예시는 기능의 경계를 설명하는 것이며 특정 조직의 승인 정책을 대신 정하는 것은 아니다.

 

이후 같은 질문군으로 전후를 비교한다. 도구 선택과 인자 오류가 줄었는지, 추가 질문이 필요한 경우를 놓치지 않는지, 반환 결과의 크기와 전체 호출 수가 어떻게 변했는지 본다. 가장 중요한 것은 실제 업무 상태와 최종 안내가 맞는지다. 더 짧은 호출 경로가 언제나 더 나은 결과는 아니다.

성공률만 보지 말고 호출 경로와 실제 결과를 확인하자

Anthropic은 현실적인 데이터와 검증 가능한 결과를 가진 평가 과제를 권한다. 도구 이름과 ID를 문제에 모두 적어 주면 호출 형식은 시험할 수 있지만 실제 사용자의 자연어 요청에서 선택하는 능력은 덜 시험하게 된다. 업무의 모호함과 여러 단계의 연결을 포함한 문제도 필요하다.

 

다만 정답 경로를 하나로 고정하는 평가도 조심해야 한다. 서로 다른 도구 조합으로 같은 올바른 결과를 만들 수 있다. 특정 호출 순서를 따라야만 정답으로 처리하면 유효한 대안을 실패로 판정할 수 있다. 반드시 지켜야 할 권한과 부작용 제한은 엄격하게 확인하되, 허용 가능한 해결 경로의 다양성은 인정해야 한다.

 

실행 기록에서는 첫 번째 잘못된 선택이 어디인지 살펴보자. 이름이 비슷해 혼동했는지, 필드 의미를 틀렸는지, 빈 결과를 잘못 해석했는지 구분한다. 최종 답변의 자연스러움보다 도구 요청과 응답, 실제 외부 상태를 함께 확인해야 한다. 모델의 설명이 실행 기록을 완벽히 대신하지는 않는다.

 

측정 항목에는 업무 완료율 외에 무효 인자 비율, 불필요한 호출, 반환 토큰, 재시도, 전체 지연과 비용을 넣을 수 있다. 민감한 원문을 모두 기록할 필요는 없으며 필요한 메타데이터와 안전한 참조를 정한다. 여러 지표를 모으되 무엇이 원인이고 무엇이 결과인지 혼동하지 않도록 한다.

설명문과 스키마, 출력 형식을 고칠 때는 변경 범위를 나누고 보지 않은 평가군으로 확인하자. 특정 실패 사례에 맞춰 예시를 계속 붙이면 다른 요청에서 성능이 떨어질 수 있다. 모델이나 도구 구현이 바뀌었을 때도 같은 계약이 유지되는지 점검해야 한다. 도구 정의는 한 번 작성하고 끝내는 문서가 아니라 운영 중인 인터페이스다.

자주 묻는 질문

Q. API가 정상 동작하면 에이전트용 도구도 잘 만든 것 아닌가요?

API 구현이 정확해도 모델이 용도를 이해하고 인자를 채우며 결과를 해석하는 과정은 별도로 확인해야 한다. 도구 이름과 설명, 입력 및 출력의 의미가 실제 업무와 연결되는지 평가해야 한다. 서버의 형식 검증만으로 선택 품질이 보장되지는 않는다.

Q. strict 모드를 켜면 잘못된 도구 호출이 사라지나요?

지원하는 스키마 형식을 지키는 데 도움이 되지만 인자의 업무적 의미와 권한까지 보장하는 것은 아니다. 다른 고객의 주문 번호나 틀린 날짜도 올바른 자료형으로 출력할 수 있다. 형식, 의미, 권한과 실행 결과를 나눠 확인해야 한다.

Q. 도구 설명은 길수록 좋은가요?

필요한 정보가 분명해야 하지만 길이 자체가 목표는 아니다. 용도와 구분 조건, 인자와 반환값의 의미를 담고 반복되는 오류를 바로잡는 설명을 추가하는 편이 좋다. 모델과 과제에 따라 예시 추가가 항상 개선을 만들지는 않으므로 평가가 필요하다.

Q. 반환값을 줄이면 정확도도 자동으로 올라가나요?

관련 없는 정보를 줄이면 도움이 될 수 있지만 필수 근거와 예외까지 없애면 오히려 틀릴 수 있다. 다음 판단에 필요한 내용과 제한 사항을 보존해야 한다. 잘린 결과나 일부 실패는 명확히 표시하는 편이 좋다.

Q. 모든 기능을 하나의 만능 도구로 합치는 것이 효율적인가요?

호출 수는 줄 수 있어도 입력과 부작용의 경계가 복잡해질 수 있다. 항상 함께 쓰이는 읽기 작업은 통합을 검토할 수 있지만 변경과 권한 및 검증 단위는 따로 봐야 한다. 대표 업무에서 전체 성공과 비용을 비교해야 한다.

Q. 도구 검색을 도입하면 많은 도구 문제는 해결되나요?

필요할 때 관련 도구를 불러오는 데 도움이 될 수 있지만 검색 단계의 누락이 새로운 실패 원인이 될 수 있다. 후보가 포함되는지와 로딩된 도구를 올바르게 호출하는지 나누어 평가해야 한다. 현재 모델과 API의 지원 범위도 확인해야 한다.

도구 설계는 프롬프트 밖에 있는 프롬프트 엔지니어링이다

AI 에이전트가 읽는 것은 사용자 요청만이 아니다. 도구의 이름과 설명, 스키마, 오류 메시지와 실행 결과도 다음 행동에 영향을 준다. 따라서 도구 설계는 API를 연결하는 작업인 동시에 에이전트의 선택 환경을 설계하는 일이다. 프롬프트만 고쳐서는 풀기 어려운 실패가 인터페이스에서 시작될 수 있다.

 

좋은 도구는 선택의 경계를 드러내고, 이미 확정된 값을 추측시키지 않으며, 다음 판단에 필요한 정보를 반환한다. 실패했을 때는 고칠 수 있는 부분과 넘지 말아야 할 경계를 알려 준다. 이를 실제 업무와 결과로 검증할 때, 정상적인 코드와 올바른 에이전트 행동 사이의 간격을 줄일 수 있다.

공식 자료와 국내 기술 블로그 참고 자료

Anthropic, Writing effective tools for agents — with agents. 2025년 9월 11일 공개. 업무에 맞는 도구의 범위, 이름 공간, 응답의 의미와 길이, 오류 복구 및 평가 기반 개선 원칙을 확인했다. 특정 평가의 성능 향상을 모든 도구와 모델의 보장으로 일반화하지 않았다. 원문: https://www.anthropic.com/engineering/writing-tools-for-agents

 

OpenAI 공식 문서, Function calling. 호출과 애플리케이션 실행의 흐름, 명세 작성, 이미 아는 인자 처리, strict 모드와 도구 선택 범위 및 지연 로딩의 개념을 확인했다. 세부 API 형식과 기본값은 실제 사용하는 버전에 맞춰 확인해야 한다. 원문: https://platform.openai.com/docs/guides/function-calling

Function calling | OpenAI API

 

카카오페이 기술 블로그, AI Agent, 넌 누구냐 1 - Tool, MCP, Skill, Harness는 무엇인가. 2026년 9월 1일 게시. 한국어로 도구 명세와 실제 실행 주체를 구분하는 설명 및 개념 전개를 참고했다. 개별 제품의 동작이나 비용을 모든 에이전트의 동일한 성질로 옮기지 않았다. 원문: https://tech.kakaopay.com/post/ai-agent-1/

AI Agent, 넌 누구냐 1 - Tool, MCP, Skill, Harness는 무엇인가 | 카카오페이 기술 블로그

 

deep gadget by ManyCoreSoft, AI 에이전트의 작동 원리: 도구 선택에서 실행까지. 2026년 8월 6일 게시. 사용자 요청에서 호출과 결과 확인으로 이어지는 국내 기술 블로그의 사례 설명 형식을 비교했다. 본문의 배송 상담 예시는 별도로 구성한 가상 설계다. 원문: https://www.deepgadget.com/blog/how-ai-agents-work-llm-tool-calling/