에이전트와 함께 효과적인 도구 작성하기

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

에이전트는 우리가 제공하는 도구만큼만 효과적입니다. 우리는 고품질 도구와 평가를 작성하는 방법, 그리고 Claude를 활용해 도구 자체의 성능을 최적화하여 성능을 높이는 방법을 공유합니다.

Model Context Protocol(MCP)은 LLM 에이전트에게 수백 개의 도구를 제공하여 실제 과제를 해결할 수 있게 합니다. 하지만 이러한 도구를 최대한 효과적으로 만들려면 어떻게 해야 할까요?

이 글에서는 다양한 에이전트 기반 AI 시스템에서 성능을 향상시키는 데 가장 효과적인 기술을 설명합니다.

먼저 다음과 같은 방법을 다룹니다:

• 도구의 프로토타입을 구축하고 테스트하기
• 에이전트와 함께 도구의 포괄적인 평가를 생성하고 실행하기
• Claude Code와 같은 에이전트와 협업하여 도구의 성능을 자동으로 높이기

마지막으로, 우리가 도출한 고품질 도구 작성의 핵심 원칙을 정리합니다:

• 구현할(혹은 구현하지 않을) 올바른 도구 선택하기
• 네임스페이싱을 통해 기능의 경계를 명확히 정의하기
• 도구에서 에이전트로 의미 있는 컨텍스트 반환하기
• 토큰 효율성을 위해 도구 응답 최적화하기
• 도구 설명과 명세에 프롬프트 엔지니어링 적용하기

도구 평가를 구축하면 도구의 성능을 체계적으로 측정할 수 있습니다. Claude Code를 활용하면 이 평가 기준에 따라 도구를 자동으로 최적화할 수 있습니다.

도구란 무엇인가?

컴퓨팅에서 결정론적 시스템은 동일한 입력이 주어지면 항상 같은 출력을 생성합니다. 반면, 비결정론적 시스템(에이전트 등)은 동일한 조건에서도 다양한 응답을 생성할 수 있습니다.

전통적으로 소프트웨어를 작성할 때는 결정론적 시스템 간의 계약을 설정합니다. 예를 들어, ‎⁠getWeather("NYC")⁠와 같은 함수 호출은 호출할 때마다 항상 동일한 방식으로 뉴욕의 날씨를 가져옵니다.

도구는 결정론적 시스템과 비결정론적 에이전트 간의 계약을 반영하는 새로운 유형의 소프트웨어입니다. 사용자가 “오늘 우산을 가져가야 할까?“라고 묻는다면, 에이전트는 날씨 도구를 호출하거나, 일반 지식으로 답하거나, 위치에 대해 추가 질문을 할 수도 있습니다. 때로는 에이전트가 환각을 일으키거나 도구 사용법을 제대로 이해하지 못할 수도 있습니다.

따라서 에이전트용 소프트웨어를 작성할 때는 기존의 함수나 API 작성 방식이 아니라, 에이전트를 위해 도구와 MCP 서버를 설계해야 합니다.

우리의 목표는 에이전트가 다양한 성공 전략을 추구할 수 있도록 도구를 활용해 더 넓은 범위의 과제를 효과적으로 해결할 수 있게 하는 것입니다. 다행히도, 에이전트에게 가장 “인체공학적”인 도구는 인간에게도 직관적으로 이해하기 쉬운 경우가 많았습니다.

도구 작성 방법

이 섹션에서는 에이전트와 협업하여 도구를 작성하고 개선하는 방법을 설명합니다. 먼저 도구의 프로토타입을 빠르게 구축하고 로컬에서 테스트하세요. 다음으로, 평가를 실행하여 변경 사항을 측정합니다. 에이전트와 함께 평가 및 개선 과정을 반복하면 실제 과제에서 에이전트가 강력한 성능을 달성할 수 있습니다.

프로토타입 구축

어떤 도구가 에이전트에게 인체공학적일지, 그렇지 않을지 예측하기는 어렵습니다. 직접 빠르게 프로토타입을 구축해보세요. Claude Code를 사용해 도구를 작성할 때(원샷으로도 가능), 도구가 의존하는 소프트웨어 라이브러리, API, SDK(예: MCP SDK)에 대한 문서를 Claude에게 제공하면 도움이 됩니다. LLM 친화적인 문서는 공식 문서 사이트의 ‎⁠llms.txt⁠ 파일에서 흔히 찾을 수 있습니다(예: 우리의 API).

도구를 로컬 MCP 서버나 Desktop extension(DXT)에 래핑하면 Claude Code나 Claude Desktop 앱에서 도구를 연결하고 테스트할 수 있습니다.

로컬 MCP 서버를 Claude Code에 연결하려면 ‎⁠claude mcp add <name> <command> [args...]⁠를 실행하세요.

로컬 MCP 서버나 DXT를 Claude Desktop 앱에 연결하려면 각각 ‎⁠Settings > Developer⁠ 또는 ‎⁠Settings > Extensions⁠로 이동하세요.

도구는 Anthropic API 호출에 직접 전달하여 프로그래밍적으로 테스트할 수도 있습니다.

도구를 직접 테스트하여 거친 부분을 찾아내세요. 사용자로부터 피드백을 받아 도구가 지원할 것으로 기대되는 사용 사례와 프롬프트에 대한 직관을 쌓으세요.

평가 실행

다음으로, Claude가 도구를 얼마나 잘 사용하는지 평가를 실행하여 측정해야 합니다. 실제 사용 사례를 기반으로 다양한 평가 과제를 많이 생성하는 것부터 시작하세요. 결과 분석과 도구 개선 방안 도출을 위해 에이전트와 협업할 것을 권장합니다. 이 전체 과정을 우리의 도구 평가 안내서에서 확인할 수 있습니다.

내부 Slack 도구의 홀드아웃 테스트 세트 성능

평가 과제 생성

초기 프로토타입을 바탕으로 Claude Code는 도구를 빠르게 탐색하고 수십 개의 프롬프트-응답 쌍을 만들 수 있습니다. 프롬프트는 실제 사용 사례에서 영감을 얻고, 현실적인 데이터 소스와 서비스(예: 내부 지식베이스, 마이크로서비스)를 기반으로 해야 합니다. 너무 단순하거나 피상적인 “샌드박스” 환경은 도구를 충분히 복잡하게 스트레스 테스트하지 못하므로 피하세요. 강력한 평가 과제는 여러 번의 도구 호출(수십 번까지)도 필요할 수 있습니다.

강력한 과제 예시:

• Jane과 다음 주에 Acme Corp 프로젝트 논의를 위한 미팅을 예약하세요. 지난 프로젝트 계획 미팅의 노트를 첨부하고 회의실을 예약하세요.
• 고객 ID 9182가 단일 구매 시도에 대해 세 번 청구되었다고 신고했습니다. 관련 로그 항목을 모두 찾고, 동일한 문제가 발생한 다른 고객이 있는지 확인하세요.
• 고객 Sarah Chen이 취소 요청을 제출했습니다. 유지 오퍼를 준비하세요. (1) 이탈 사유, (2) 가장 효과적인 유지 오퍼, (3) 오퍼 제안 전 주의해야 할 위험 요인을 파악하세요.

약한 과제 예시:

• jane@acme.corp와 다음 주에 미팅을 예약하세요.
• ‎⁠purchase_complete⁠ 및 ‎⁠customer_id=9182⁠로 결제 로그를 검색하세요.
• 고객 ID 45892의 취소 요청을 찾으세요.

각 평가 프롬프트는 검증 가능한 응답 또는 결과와 짝지어야 합니다. 검증기는 정답과 샘플 응답 간의 단순 문자열 비교부터, Claude에게 응답을 평가하게 하는 고급 방식까지 다양할 수 있습니다. 형식, 구두점, 대안 표현 등으로 인해 올바른 응답을 잘못 거부하는 과도하게 엄격한 검증기는 피하세요.

각 프롬프트-응답 쌍마다, 에이전트가 과제를 해결할 때 호출할 것으로 기대되는 도구를 명시적으로 지정할 수도 있습니다. 이를 통해 에이전트가 평가 중 각 도구의 목적을 제대로 파악하는지 측정할 수 있습니다. 하지만 과제를 올바르게 해결하는 경로가 여러 개일 수 있으므로, 전략을 과도하게 명시하거나 과적합하지 않도록 주의하세요.

평가 실행

평가는 LLM API를 직접 호출하여 프로그래밍적으로 실행하는 것이 좋습니다. 간단한 에이전트 루프(LLM API와 도구 호출을 번갈아 감싸는 ‎⁠while⁠ 루프)를 사용하세요. 각 평가 과제마다 하나의 루프를 만듭니다. 평가 에이전트의 시스템 프롬프트에는 구조화된 응답 블록(검증용)뿐 아니라, 추론 및 피드백 블록도 출력하도록 지시하세요. 이러한 블록을 도구 호출 및 응답 블록보다 먼저 출력하도록 하면, 연쇄적 사고(chain-of-thought, CoT) 행동을 유도하여 LLM의 지능을 높일 수 있습니다.

Claude로 평가를 실행할 때는 interleaved thinking을 켜면 유사한 기능을 바로 사용할 수 있습니다. 이를 통해 에이전트가 특정 도구를 호출하지 않는 이유, 도구 설명 및 명세의 개선점 등을 파악할 수 있습니다.

최상위 정확도뿐 아니라, 개별 도구 호출 및 과제의 총 실행 시간, 도구 호출 횟수, 토큰 소비량, 도구 오류 등 다양한 지표를 수집하세요. 도구 호출을 추적하면 에이전트가 추구하는 일반적인 워크플로를 파악할 수 있고, 도구 통합 기회도 발견할 수 있습니다.

내부 Asana 도구의 홀드아웃 테스트 세트 성능

결과 분석

에이전트는 모순된 도구 설명, 비효율적인 도구 구현, 혼란스러운 도구 스키마 등 다양한 문제를 발견하고 피드백을 제공하는 데 유용한 파트너입니다. 하지만 에이전트가 피드백과 응답에서 생략하는 내용이 포함하는 내용보다 더 중요할 수 있다는 점을 명심하세요. LLM은 항상 “의도한 대로 말하지” 않습니다.

에이전트가 막히거나 혼란스러워하는 부분을 관찰하세요. 평가 에이전트의 추론 및 피드백(CoT)을 읽고 거친 부분을 파악하세요. 원시 대화 기록(도구 호출 및 응답 포함)을 검토하여 CoT에 명시적으로 드러나지 않은 행동도 확인하세요. 평가 에이전트가 반드시 정답이나 전략을 알고 있는 것은 아니므로, 행간을 읽으세요.

도구 호출 지표를 분석하세요. 중복된 도구 호출이 많으면 페이지네이션이나 토큰 제한 파라미터를 조정해야 할 수 있고, 잘못된 파라미터로 인한 도구 오류가 많으면 도구 설명이나 예시를 더 명확히 해야 할 수 있습니다. Claude의 웹 검색 도구를 출시할 때, Claude가 쿼리 파라미터에 불필요하게 ‎⁠2025⁠를 추가해 검색 결과가 편향되고 성능이 저하되는 문제를 발견했습니다(도구 설명을 개선해 Claude의 행동을 바로잡았습니다).

에이전트와 협업하기

에이전트에게 결과 분석과 도구 개선을 맡길 수도 있습니다. 평가 에이전트의 대화 기록을 모두 이어붙여 Claude Code에 붙여넣으면 됩니다. Claude는 대화 기록을 분석하고 여러 도구를 한 번에 리팩터링하는 데 능숙합니다—예를 들어, 도구 구현과 설명이 새로운 변경 사항에도 일관성을 유지하도록 할 수 있습니다.

실제로 이 글의 대부분의 조언은 Claude Code로 내부 도구 구현을 반복적으로 최적화하면서 얻은 것입니다. 우리의 평가는 내부 워크스페이스를 기반으로 실제 프로젝트, 문서, 메시지 등 복잡성을 반영했습니다.

“훈련” 평가에 과적합하지 않도록 별도의 테스트 세트를 활용했습니다. 이 테스트 세트 덕분에 연구원이 직접 작성한 도구든 Claude가 생성한 도구든 “전문가” 도구 구현으로 달성한 성능을 넘어 추가적인 성능 향상을 이끌어낼 수 있었습니다.

다음 섹션에서는 이 과정을 통해 얻은 교훈을 공유합니다.

효과적인 도구 작성 원칙

이 섹션에서는 효과적인 도구 작성에 대한 몇 가지 핵심 원칙을 정리합니다.

에이전트에 적합한 도구 선택하기

도구가 많다고 항상 더 나은 결과가 나오는 것은 아닙니다. 흔히 볼 수 있는 오류는 기존 소프트웨어 기능이나 API 엔드포인트를 단순히 래핑한 도구를 만드는 것입니다—에이전트에 적합한지 여부와 관계없이 말이죠. 에이전트는 기존 소프트웨어와는 다른 “어포던스”(도구를 통해 취할 수 있는 잠재적 행동 방식)를 갖고 있기 때문입니다.

LLM 에이전트는 “컨텍스트”(한 번에 처리할 수 있는 정보의 양)에 제한이 있지만, 컴퓨터 메모리는 저렴하고 풍부합니다. 예를 들어, 주소록에서 연락처를 검색하는 작업을 생각해보세요. 전통적인 소프트웨어는 연락처 목록을 하나씩 효율적으로 저장하고 처리할 수 있습니다.

하지만 LLM 에이전트가 모든 연락처를 반환하는 도구를 사용하고, 각 연락처를 토큰 단위로 읽어야 한다면, 제한된 컨텍스트 공간을 불필요한 정보로 낭비하게 됩니다(주소록을 페이지별로 읽으며 연락처를 찾는 것과 같습니다—즉, 무차별 대입 방식). 더 나은 접근법은(에이전트와 인간 모두에게) 관련 페이지로 바로 이동하는 것입니다(예: 알파벳순으로 찾기).

평가 과제에 맞는 몇 가지 핵심 워크플로에 집중하는 도구를 신중하게 구축하고, 그 후 확장하는 것이 좋습니다. 주소록의 경우, ‎⁠search_contacts⁠나 ‎⁠message_contact⁠ 도구를 구현하는 것이 ‎⁠list_contacts⁠ 도구를 만드는 것보다 더 적합할 수 있습니다.

도구는 여러 개의 개별 작업(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 서버와 수백 개의 다양한 도구(다른 개발자가 만든 도구 포함)에 접근할 수 있습니다. 도구의 기능이 겹치거나 목적이 모호하면, 에이전트가 어떤 도구를 사용해야 할지 혼란스러워할 수 있습니다.

네임스페이싱(관련 도구를 공통 접두사로 그룹화)은 많은 도구 사이의 경계를 구분하는 데 도움이 됩니다. MCP 클라이언트는 때때로 이를 기본적으로 적용합니다. 예를 들어, 서비스별(‎⁠asana_search⁠, ‎⁠jira_search⁠)이나 리소스별(‎⁠asana_projects_search⁠, ‎⁠asana_users_search⁠)로 도구를 네임스페이싱하면 에이전트가 적절한 시점에 올바른 도구를 선택할 수 있습니다.

접두사/접미사 기반 네임스페이싱 선택이 도구 사용 평가에 미묘한 영향을 미치는 것을 발견했습니다. 효과는 LLM마다 다르므로, 자체 평가에 따라 네이밍 방식을 선택하는 것이 좋습니다.

에이전트는 잘못된 도구를 호출하거나, 올바른 도구를 잘못된 파라미터로 호출하거나, 도구를 너무 적게 호출하거나, 도구 응답을 잘못 처리할 수 있습니다. 자연스러운 작업 분할을 반영하는 이름의 도구를 선택적으로 구현하면, 에이전트가 로드하는 도구 및 도구 설명의 수를 줄이고, 에이전트의 컨텍스트에서 도구 호출로 연산을 오프로드할 수 있습니다. 이는 에이전트의 실수 위험을 줄여줍니다.

도구에서 의미 있는 컨텍스트 반환하기

도구 구현은 에이전트에게 신호가 강한 정보만 반환하도록 주의해야 합니다. 컨텍스트의 관련성을 우선시하고, 유연성을 위해 저수준 기술 식별자(‎⁠uuid⁠, ‎⁠256px_image_url⁠, ‎⁠mime_type⁠ 등)는 피하세요. ‎⁠name⁠, ‎⁠image_url⁠, ‎⁠file_type⁠ 같은 필드는 에이전트의 후속 행동과 응답에 직접적으로 도움이 됩니다.

에이전트는 자연어 이름, 용어, 식별자를 암호화된 식별자보다 훨씬 더 잘 다룹니다. 임의의 알파벳-숫자 UUID를 더 의미 있고 해석 가능한 언어(혹은 0부터 시작하는 ID 체계)로 변환하는 것만으로도 Claude의 검색 정확도가 크게 향상되고 환각이 줄어드는 것을 확인했습니다.

경우에 따라, 에이전트가 자연어와 기술 식별자 모두를 다룰 수 있어야 할 수도 있습니다(예: ‎⁠search_user(name='jane')⁠ → ‎⁠send_message(id=12345)⁠). 이를 위해 도구에 간단한 ‎⁠response_format⁠ enum 파라미터를 추가하여, 에이전트가 도구가 ‎⁠“concise”⁠ 또는 ‎⁠“detailed”⁠ 응답을 반환하도록 제어할 수 있게 할 수 있습니다.

더 많은 형식을 추가해 유연성을 높일 수도 있습니다. GraphQL처럼 원하는 정보만 선택적으로 받을 수 있습니다. 다음은 도구 응답의 상세도를 제어하는 ResponseFormat enum 예시입니다:

enum ResponseFormat {
   DETAILED = "detailed",
   CONCISE = "concise"
}

자세한 도구 응답 예시(206 토큰):

간결한 도구 응답 예시(72 토큰):

Slack 스레드와 스레드 답글은 고유한 thread_ts로 식별되며, thread_ts 및 기타 ID(channel_id, user_id)는 “detailed” 도구 응답에서 가져와야 추가 도구 호출에 사용할 수 있습니다. “concise” 도구 응답은 스레드 내용만 반환하고 ID는 제외합니다. 이 예시에서 “concise” 응답은 “detailed” 응답의 약 ⅓ 토큰만 사용합니다.

도구 응답 구조(XML, JSON, Markdown 등)도 평가 성능에 영향을 줄 수 있습니다. LLM은 다음 토큰 예측에 기반해 학습되므로, 학습 데이터와 일치하는 형식에서 더 잘 동작하는 경향이 있습니다. 최적의 응답 구조는 과제와 에이전트마다 크게 다르므로, 자체 평가를 통해 최적의 구조를 선택하세요.

도구 응답의 토큰 효율성 최적화

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

페이지네이션, 범위 선택, 필터링, 절단 등 여러 방법을 조합해, 많은 컨텍스트를 소모할 수 있는 도구 응답에는 합리적인 기본 파라미터 값을 적용하세요. Claude Code에서는 기본적으로 도구 응답을 25,000 토큰으로 제한합니다. 에이전트의 실질적인 컨텍스트 길이는 앞으로 늘어나겠지만, 컨텍스트 효율적인 도구의 필요성은 계속될 것입니다.

응답을 절단할 경우, 에이전트가 더 토큰 효율적인 전략을 추구하도록 명확한 지침을 제공하세요. 예를 들어, 지식 검색 과제에서 한 번에 넓게 검색하기보다 여러 번 작고 타겟팅된 검색을 하도록 유도할 수 있습니다. 도구 호출에서 오류가 발생하면(예: 입력 검증 중), 오류 응답을 프롬프트 엔지니어링하여 구체적이고 실행 가능한 개선점을 명확히 전달하세요. 불투명한 오류 코드나 트레이스백은 피하세요.

절단된 도구 응답 예시:

도움이 되지 않는 오류 응답 예시:

도움이 되는 오류 응답 예시:

도구 절단 및 오류 응답은 에이전트가 필터나 페이지네이션을 활용하는 등 더 토큰 효율적인 도구 사용 행동을 유도하거나, 올바른 도구 입력 예시를 제공할 수 있습니다.

도구 설명 프롬프트 엔지니어링

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

도구 설명과 명세를 작성할 때는, 팀의 신입에게 도구를 설명한다고 생각하세요. 암묵적으로 전달할 수 있는 컨텍스트—특수 쿼리 형식, 용어 정의, 리소스 간 관계 등—를 명확히 드러내세요. 모호함을 피하고, 기대되는 입력과 출력을 명확히 설명(엄격한 데이터 모델로 강제)하세요. 특히 입력 파라미터는 명확하게 이름을 지정하세요: ‎⁠user⁠ 대신 ‎⁠user_id⁠와 같이.

평가를 통해 프롬프트 엔지니어링의 효과를 더 확신 있게 측정할 수 있습니다. 도구 설명의 작은 개선만으로도 큰 성능 향상을 얻을 수 있습니다. Claude Sonnet 3.5는 도구 설명을 정밀하게 개선한 후, SWE-bench Verified 평가에서 최첨단 성능을 달성했습니다. 오류율이 크게 줄고 과제 완료율이 높아졌습니다.

도구 정의에 대한 기타 모범 사례는 Developer Guide에서 확인할 수 있습니다. Claude용 도구를 구축한다면, 도구가 Claude의 시스템 프롬프트에 동적으로 로드되는 방식도 참고하세요. MCP 서버용 도구를 작성한다면, tool annotations를 통해 어떤 도구가 오픈월드 접근이나 파괴적 변경을 요구하는지 공개할 수 있습니다.

앞으로의 전망

에이전트용 효과적인 도구를 구축하려면, 예측 가능한 결정론적 패턴에서 비결정론적 패턴으로 소프트웨어 개발 관행을 재정립해야 합니다.

이 글에서 설명한 반복적이고 평가 중심의 과정을 통해, 성공적인 도구의 일관된 패턴을 확인했습니다: 효과적인 도구는 의도적으로 명확하게 정의되고, 에이전트 컨텍스트를 신중하게 사용하며, 다양한 워크플로에서 결합될 수 있고, 에이전트가 직관적으로 실제 과제를 해결할 수 있게 합니다.

앞으로는 에이전트가 세상과 상호작용하는 구체적인 메커니즘이 발전할 것으로 기대합니다—MCP 프로토콜의 업데이트, LLM 자체의 업그레이드 등. 평가 중심의 체계적인 도구 개선 접근법을 통해, 에이전트가 더 강력해질수록 그들이 사용하는 도구도 함께 발전할 수 있습니다.