한 개발자가 일부러 이름이 비슷하고 입력값까지 똑같은 도구 두 개를 만들어, AI가 둘을 구분할 단서를 '설명 한 줄'만 남겨 뒀어요. 그 상태로 '애플 시가총액?'을 다섯 번 물었더니, 설명이 얇을 땐 다섯 번 다 엉뚱한 도구를 골랐다고 해요. 버그는 에이전트 코드가 아니라 도구 설명 한 문장이었던 거죠. 앤트로픽 공식 문서도 '설명이 도구 성능을 좌우하는 가장 중요한 요소'라고 짚는 부분과 정확히 맞닿아요.
용어 풀이
- 도구 설명(tool description)
- AI에게 '이 도구가 뭘 하고 언제 쓰는지' 알려주는 설명문. 이름·입력값만으로 부족할 때 AI가 도구를 고르는 결정적 단서가 됨.
- 도구 호출(function calling)
- AI가 답을 만들기 위해 미리 정의된 외부 기능(검색·계산·DB 조회 등)을 스스로 골라 실행하는 동작.
- 입력 스키마(input schema)
- 도구가 받는 입력값의 형식·종류를 정해 둔 명세. 두 도구의 스키마가 같으면 입력만으로는 구분이 안 됨.
- MCP(Model Context Protocol)
- AI에 외부 도구·데이터를 표준 방식으로 연결하는 규약. 여기서도 각 도구의 설명을 잘 쓰는 게 정확한 호출의 열쇠.
운영자 인사이트
도구가 늘수록 이름·입력값만으로는 구분이 모호해지는데, AI가 올바른 도구를 고르는 마지막 단서는 결국 설명 한 줄이라, MCP·에이전트 도구를 설계할 때 설명을 '무엇을·언제 쓰고·언제 쓰면 안 되는지'까지 적는 게 코드 품질만큼 중요해요.
여러 관점으로 보기
- 왜 그런가 — 공식 가이드 앤트로픽은 도구 설명이 도구 성능을 좌우하는 가장 중요한 요소라고 못박아요. 좋은 예시조차 주가 조회 도구를 드는데, 나쁜 예시가 바로 '티커 주가를 가져온다' 같은 한 줄 설명이라 이번 실험과 거의 똑같아요. Anthropic Docs
- 어떻게 고치나 — 설계 원칙 기능이 겹치거나 목적이 흐릿한 도구는 에이전트를 헷갈리게 한다고 해요. 이름에 서비스·자원을 붙여 구분하고, 설명은 새 동료에게 알려주듯 맥락까지 적으면 정확도가 크게 올라요. Anthropic Engineering