AI 에이전트를 위한 MCP 도구 설계(최적화)

  안녕하세요. 오늘은 MCP 도구 설계 최적화에 관한 글에 대해서 이야기하고자 합니다. 제가 연구 및 개발한 서비스에서, 현재 모든 MCP 서버에 아래의 글의 내용이 모두다 반영되어 있습니다. 이를 통해서, 답변의 품질, 응답의 속도 등이 크게 개선되었습니다. 그렇다면 에이전트를 위한 MCP 도구 설계 방법에 대해서 알아보도록 하겠습니다.

  AI Engineer 라면 MCP 날씨 조회 서버 예시를 작성해본 경험이 있을 것입니다. getWeather("서울")을 호출하면 항상 같은 방식으로 서울의 날씨를 가져옵니다. 하지만 AI 에이전트에게 "오늘 우산을 가져가야 할까요?"라고 묻는다면 어떨까요? 에이전트는 날씨 도구를 호출할 수도 있고, 일반 지식으로 대답할 수도 있으며, 심지어 위치를 먼저 물어볼 수도 있습니다. 같은 질문이라도 매번 다른 전략을 선택하는 것이죠. 이것이 바로 AI 에이전트 시대가 가져온 근본적인 변화입니다. 수백 개의 도구를 활용하는 LLM 에이전트가 실제 작업을 해결하도록 만들면서, 기존의 소프트웨어 개발 패러다임이 더 이상 통하지 않는다는 것을 깨달았습니다. 에이전트를 위한 도구는 단순히 API를 감싸는 것이 아니라, 결정론적 시스템과 비결정론적 시스템 사이의 새로운 '약속'을 정의하는 것입니다.

---

​◆ 결정론적 세계와 비결정론적 세계의 충돌

전통적인 컴퓨팅에서 결정론적 시스템은 동일한 입력에 대해 항상 동일한 출력을 생성합니다. 마치 자판기에 1,000원을 넣으면 항상 같은 음료수가 나오는 것과 같습니다. 이러한 예측 가능성을 바탕으로 시스템 간의 명확한 규칙을 작성해왔습니다.

개념: 비결정론적 시스템인 AI 에이전트는 같은 조건에서도 다양한 응답을 생성할 수 있습니다. 이는 에이전트가 '인식하는 가능한 행동'(affordance)이 전통적인 소프트웨어와 근본적으로 다르기 때문입니다.

비유: 같은 문제를 여러 명의 전문가에게 물어보는 상황을 상상해보세요. 어떤 전문가는 즉시 답을 제시하고, 다른 전문가는 추가 질문을 하며, 또 다른 전문가는 참고 자료를 찾아봅니다. 모두 문제를 해결하려는 목표는 같지만, 각자 다른 접근 방식을 취하는 것이죠. AI 에이전트도 마찬가지입니다.

예시: 고객 서비스 에이전트가 "고객 ID 001의 결제 문제를 해결해주세요"라는 요청을 받았을 때, 어떤 경우에는 바로 로그를 검색하고, 다른 경우에는 먼저 고객 정보를 조회하거나, 때로는 관련 문서를 찾아볼 수 있습니다. 결과는 같지만 경로는 매번 다를 수 있습니다.

이러한 비결정론적 특성 때문에 도구를 설계할 때는 완전히 새로운 사고방식이 필요합니다. 단순히 기능을 노출하는 것이 아니라, 에이전트가 직관적으로 이해하고 효과적으로 활용할 수 있도록 '인간 공학적(ergonomic)'으로 설계해야 합니다.

---

◆ 컨텍스트의 역설: 제한된 작업 기억을 가진 천재

AI 에이전트가 가진 가장 큰 제약은 바로 제한된 컨텍스트입니다. 컴퓨터 메모리는 저렴하고 풍부하지만, LLM 에이전트는 한 번에 처리할 수 있는 정보량에 명확한 한계가 있습니다.

개념: 전통적인 프로그램은 연락처 목록을 하나씩 순회하며 효율적으로 검색할 수 있습니다. 하지만 LLM 에이전트가 모든 연락처를 받아서 토큰 단위로 읽어야 한다면, 제한된 컨텍스트 공간을 무관한 정보로 낭비하게 됩니다.

비유: 전화번호부에서 특정 사람을 찾는 상황을 생각해보세요. 일반 컴퓨터는 첫 페이지부터 끝 페이지까지 효율적으로 스캔할 수 있습니다. 하지만 AI 에이전트는 마치 제한된 작업 기억을 가진 사람처럼, 각 페이지의 내용을 주의 깊게 읽고 이해해야 합니다. 이 경우 가장 좋은 방법은 알파벳 순서로 관련 페이지로 바로 건너뛰는 것입니다. 무차별 대입(brute-force) 검색이 아니라 똑똑한 검색이 필요한 것이죠.

예시: list_contacts 도구는 모든 연락처를 반환합니다. 에이전트는 이를 토큰 단위로 읽으며 관련 연락처를 찾아야 합니다. 반면 search_contacts 도구는 검색어에 맞는 연락처만 반환합니다. 후자가 에이전트에게 훨씬 더 효율적이고 자연스러운 도구입니다.

이러한 통찰은 도구 설계의 첫 번째 핵심 원칙으로 이어집니다. 더 많은 도구가 항상 더 나은 결과를 가져오는 것은 아닙니다. 오히려 신중하게 선택된 소수의 강력한 도구가 더 효과적입니다.

---

◆ 도구 통합: 여러 단계를 하나의 작업으로

효과적인 도구는 여러 개별 작업을 하나로 통합할 수 있습니다. 마치 숙련된 비서가 "다음 주에 bart0401과 회의를 잡아줘"라는 한 문장의 요청으로 여러 작업을 수행하는 것과 같습니다.

개념: 도구는 여러 개별 연산이나 API 호출을 내부적으로 처리할 수 있습니다. 관련 메타데이터로 응답을 풍부하게 만들거나, 자주 연쇄적으로 수행되는 다단계 작업을 단일 도구 호출로 처리할 수 있습니다.

예시: 다단계 작업을 단일 도구 호출로 변경한, 실제 사례

• list_users, list_events, create_event 세 개의 도구 대신, 가용성을 찾고 일정을 잡는 schedule_event 하나를 구현
• read_logs 대신, 관련 로그 라인과 주변 컨텍스트만 반환하는 search_logs를 구현
• get_customer_by_id, list_transactions, list_notes 대신, 고객의 최근 관련 정보를 한 번에 컴파일하는 get_customer_context를 구현

비유: 레스토랑에서 "스테이크 정식"을 주문하면 스테이크, 샐러드, 스프, 빵이 함께 나옵니다. 각각을 개별적으로 주문하는 것보다 훨씬 편리하고 조화롭습니다. 에이전트를 위한 도구도 마찬가지로 관련 작업들을 의미 있게 묶어야 합니다.

각 도구는 명확하고 구별되는 목적을 가져야 합니다. 도구들은 에이전트가 작업을 세분화하고 해결하는 방식이 인간이 동일한 리소스에 접근할 때와 유사하도록 설계되어야 하며, 동시에 중간 출력으로 소비될 컨텍스트를 줄여야 합니다.

---

◆ 네임스페이싱: 수백 개의 도구 속에서 길을 찾는 법

AI 에이전트는 잠재적으로 수십 개의 MCP 서버와 수백 개의 다양한 도구에 접근할 수 있습니다. 도구들이 기능적으로 겹치거나 목적이 모호하면 에이전트는 어떤 도구를 사용해야 할지 혼란스러워합니다.

개념: 네임스페이싱은 관련된 도구들을 공통 접두사로 그룹화하여 많은 도구들 사이의 경계를 명확히 합니다. 예를 들어 서비스별로(asana_search, jira_search) 또는 리소스별로(asana_projects_search, asana_users_search) 네임스페이스를 지정할 수 있습니다.

비유: 대형 도서관을 상상해보세요. 수천 권의 책이 무작위로 쌓여있다면 원하는 책을 찾기 거의 불가능합니다. 하지만 책들이 분류 체계에 따라 섹션으로 나뉘어 있다면(문학-한국문학-소설, 과학-물리학-양자역학 등), 원하는 책을 빠르게 찾을 수 있습니다. 네임스페이싱은 도구에 이러한 분류 체계를 제공합니다.

에이전트는 잘못된 도구를 호출하거나, 올바른 도구를 잘못된 매개변수로 호출하거나, 너무 적은 도구를 호출하거나, 도구 응답을 잘못 처리할 수 있습니다. 작업의 자연스러운 세분화를 반영하는 이름을 가진 도구를 선택적으로 구현함으로써, 에이전트의 컨텍스트에 로드되는 도구와 도구 설명의 수를 줄이고, 에이전트의 컨텍스트에서 도구 호출 자체로 에이전트의 계산을 오프로드할 수 있습니다.

---

◆ 의미 있는 컨텍스트만 반환하기: UUID의 저주

도구 구현은 에이전트에게 높은 신호(high signal) 정보만 반환하도록 주의해야 합니다. 유연성보다 컨텍스트 관련성을 우선시해야 하며, 낮은 수준의 기술적 식별자는 피해야 합니다.

개념: uuid, 256px_image_url, mime_type 같은 필드 대신, name, image_url, file_type 같은 필드가 에이전트의 다운스트림 작업과 응답에 직접적으로 정보를 제공할 가능성이 훨씬 높습니다. 에이전트는 암호화된 식별자보다 자연어 이름, 용어, 식별자를 훨씬 더 성공적으로 처리하는 경향이 있습니다.

예시: 임의의 영숫자 UUID를 더 의미론적으로 의미 있고 해석 가능한 언어(또는 심지어 0-인덱스 ID 체계)로 단순히 해결하는 것만으로도 환각을 줄여서, 검색 작업 정밀도를 크게 향상시켰습니다.

비유: 누군가에게 "저 사람 기억나? UUID-A7F3-9C2E-B1D4-8E5F6A2C3D1E"라고 말하는 것과 "저 사람 기억나? 지난주 회의에서 만난 bart0401"라고 말하는 것의 차이입니다. 후자가 훨씬 더 기억하기 쉽고 의미 있습니다.

일부 경우 에이전트는 자연어와 기술적 식별자 출력 모두와 상호작용할 수 있는 유연성이 필요할 수 있습니다. 예를 들어 search_user(name='jane') → send_message(id=12345) 같은 다운스트림 도구 호출을 트리거하기 위해서입니다. 이를 위해 도구에 간단한 response_format 열거형 매개변수를 노출하여 에이전트가 도구가 "concise" 또는 "detailed" 응답을 반환할지 제어 할 수 있도록 할 수 있습니다.

---

◆ 토큰 효율성: 양과 질의 균형

컨텍스트의 질을 최적화하는 것도 중요하나, 도구 응답에서 에이전트에게 반환되는 컨텍스트의 양을 최적화하는 것도 중요합니다.

개념: 많은 컨텍스트를 사용할 수 있는 모든 도구 응답에 대해 페이지네이션, 범위 선택, 필터링 및/또는 절단의 조합을 합리적인 기본 매개변수 값과 함께 구현하는 것이 좋습니다. 예로, 도구 응답의 기본값을 25,000 토큰으로 제한합니다.​

비유: 백과사전에서 정보를 찾을 때, 전체 백과사전을 읽는 것이 아니라 색인을 사용하여 관련 페이지만 찾아봅니다. 마찬가지로 도구도 관련 정보만 간결하게 제공해야 합니다.

예시: 도구 호출이 오류를 발생시키는 경우(예: 입력 유효성 검사 중), 불투명한 오류 코드나 트레이스백이 아니라 명확하고 실행 가능한 개선 사항을 명확하게 전달하도록 오류 응답을 설계합니다.

- 도움이 되지 않는 오류 응답의 예시
→ Error: Invalid input (어떤 부분이 잘못되었는지 명확하지 않음).
- 도움이 되는 오류 응답의 예시
→  Error: The 'date' parameter must be in YYYY-MM-DD format.
                You provided '2025/11/17'. Please use '2025-11-17' instead .

---

◆ 프롬프트 엔지니어링: 도구 정의 및 설명의 마법

도구를 개선하는 가장 효과적인 방법 중 하나는 바로 도구 정의과 설명을 프롬프트 엔지니어링하는 것입니다. 이들은 에이전트의 컨텍스트에 로드되므로 효과적인 도구 호출 행동을 효율적으로 유도할 수 있습니다.

개념: 도구 정의과 설명을 작성할 때는, 암묵적으로 가져올 수 있는 컨텍스트(특수 쿼리 형식, 전문 용어의 정의, 기본 리소스 간의 관계)를 명시적으로 만드세요. 명확하게 설명하고 엄격한 데이터 모델로 강제하여 모호함을 피하게 설계하여야 합니다.

예시: 입력 매개변수는 명확하게 명명되어야 합니다. user라는 매개변수 대신 user_id라는 매개변수를 사용하세요. 도구 설명에 대한 작은 개선조차도 극적인 향상을 가져올 수 있습니다. ​

비유: 제품 설명서를 작성하는 것과 같습니다. "이것을 저것에 연결하세요"보다 "빨간색 케이블을 기기 뒷면의 'HDMI IN' 포트에 연결하세요"가 훨씬 더 명확하고 따라하기 쉽습니다.

---

마무리하며

AI 에이전트를 위한 효과적인 도구를 구축하려면 예측 가능한 결정론적 패턴에서, 비결정론적 패턴으로 MCP 도구를 설계하여야 합니다. 효과적인 도구는 의도적이고 명확하게 정의되며, 에이전트 컨텍스트를 신중하게 사용하고, 다양한 워크플로우에서 함께 결합될 수 있으며, 에이전트가 실제 작업을 직관적으로 해결할 수 있게 합니다. ​

---

https://www.anthropic.com/engineering/writing-tools-for-agents

Writing effective tools for AI agents—using AI agents