# (번역) 에이전트를 위한 효과적인 도구 작성 — 에이전트와 함께

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

게시일: 2025년 9월 11일

에이전트의 효과성은 우리가 제공하는 도구의 수준에 달려 있습니다. 고품질 도구와 평가를 작성하는 방법, 그리고 Claude를 활용해 스스로 도구를 최적화함으로써 성능을 향상시키는 방법을 공유합니다.

[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)은 LLM 에이전트에게 실제 업무를 해결할 수 있는 수백 가지 도구를 제공할 수 있습니다. 하지만 이러한 도구의 효과를 극대화하려면 어떻게 해야 할까요? 본 글에서는 다양한 에이전트형 AI 시스템의 성능을 향상시키는 가장 효과적인 기법들[^1]을 설명합니다.

먼저 다음을 수행하는 방법을 다룹니다:


* 도구 프로토타입 구축 및 테스트
* 에이전트를 활용한 도구 종합 평가 생성 및 실행
* Claude Code와 같은 에이전트와의 협업을 통한 도구 성능 자동 향상 


마지막으로, 고품질 도구 작성의 핵심 원칙을 제시합니다: 


* 구현할 도구(및 구현하지 않을 도구) 선택
* 기능 경계를 명확히 정의하기 위한 도구 네임스페이싱
* 도구 응답의 토큰 효율성 최적화 
* 도구 설명 및 사양의 프롬프트 엔지니어링 


![엔지니어가 Claude Code를 활용해 에이전트형 도구의 효능을 평가하는 과정을 묘사한 이미지입니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fcdc027ad2730e4732168bb198fc9363678544f99-1920x1080.png&w=3840&q=75)

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


## 도구란 무엇인가? 


컴퓨팅에서 결정론적 시스템은 동일한 입력에 대해 매번 동일한 출력을 생성하는 반면, 에이전트와 같은 _비결정론적_ 시스템은 동일한 시작 조건에서도 다양한 응답을 생성할 수 있습니다.

기존 소프트웨어 개발은 결정론적 시스템 간의 계약을 수립하는 것입니다. 예를 들어 `getWeather("NYC")` 함수 호출은 매번 정확히 동일한 방식으로 뉴욕시 날씨를 가져옵니다.

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

이는 에이전트용 소프트웨어 작성 방식을 근본적으로 재고해야 함을 의미합니다: 다른 개발자나 시스템을 위한 함수나 API를 작성하는 방식이 아니라, 에이전트를 위해 도구와 [MCP 서버](https://modelcontextprotocol.io/)를 설계해야 합니다.

목표는 에이전트가 다양한 성공 전략을 추구할 수 있도록 도구를 활용해 광범위한 작업 해결에 효과적으로 대응할 수 있는 영역을 확대하는 것입니다. 다행히 경험상 에이전트에게 가장 '인체공학적'인 도구들은 인간에게도 놀라울 정도로 직관적으로 이해됩니다. 


## 도구 작성 방법 


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


### 프로토타입 구축


직접 체험해 보지 않고서는 에이전트가 어떤 도구를 인체공학적으로 느낄지 예측하기 어려울 수 있습니다. 도구의 빠른 프로토타입을 구축하는 것으로 시작하세요. 도구를 작성할 때 [Claude Code](https://www.anthropic.com/claude-code)를 사용한다면(일회성 실행 가능), 도구가 의존할 소프트웨어 라이브러리, API, SDK([MCP SDK](https://modelcontextprotocol.io/docs/sdk) 포함)에 대한 문서를 Claude에 제공하는 것이 도움이 됩니다. LLM 친화적인 문서는 공식 문서 사이트의 평면 `llms.txt` 파일에서 흔히 찾을 수 있습니다(저희 [API 문서](https://docs.anthropic.com/llms.txt) 참조).

도구를 [로컬 MCP 서버](https://modelcontextprotocol.io/docs/develop/connect-local-servers) 또는 [데스크톱 확장 프로그램](https://www.anthropic.com/engineering/desktop-extensions) (DXT)로 묶으면 Claude Code 또는 Claude 데스크톱 앱에서 도구를 연결하고 테스트할 수 있습니다.

로컬 MCP 서버를 Claude Code에 연결하려면 `claude mcp add <이름> <명령어> [인수...]`를 실행하세요. 로컬 MCP 서버 또는 DXT를 Claude Desktop 앱에 연결하려면 각각 `설정 > 개발자` 또는 `설정 > 확장 프로그램`으로 이동하세요.

도구는 프로그래밍 방식 테스트를 위해 [Anthropic API](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview) 호출에 직접 전달할 수도 있습니다. 도구를 직접 테스트하여 미흡한 부분을 파악하세요. 사용자로부터 피드백을 수집하여 도구가 지원할 것으로 기대되는 사용 사례와 프롬프트에 대한 통찰력을 구축하세요.

### 평가 실행 


다음으로, 평가를 실행하여 Claude가 도구를 얼마나 잘 활용하는지 측정해야 합니다. 실제 사용 사례를 기반으로 한 다량의 평가 과제를 생성하는 것으로 시작하세요. 결과 분석 및 도구 개선 방안을 도출하기 위해 에이전트와의 협업을 권장합니다. [도구 평가 가이드](https://github.com/anthropics/anthropic-cookbook/blob/main/tool_evaluation/tool_evaluation.ipynb)에서 이 프로세스의 전체 단계를 확인하세요.

![이 그래프는 인간이 작성한 Slack MCP 서버와 Claude가 최적화한 Slack MCP 서버의 테스트 세트 정확도를 비교합니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F6e810aee67f3f3c955832fb7bf9033ffb0102000-1920x1080.png&w=3840&q=75)

내부 Slack 도구의 홀드아웃 테스트 세트 성능 평가 작업 생성 초기 프로토타입을 통해 Claude Code는 도구를 신속하게 탐색하고 수십 개의 프롬프트-응답 쌍을 생성할 수 있습니다. 프롬프트는 실제 사용 사례에서 영감을 얻어야 하며, 현실적인 데이터 소스 및 서비스(예: 내부 지식베이스 및 마이크로서비스)를 기반으로 해야 합니다. 도구의 복잡성을 충분히 검증하지 못하는 지나치게 단순하거나 피상적인 "샌드박스" 환경은 피하는 것이 좋습니다. 강력한 평가 작업은 여러 도구 호출(수십 번에 이를 수 있음)을 필요로 할 수 있습니다. 강력한 작업의 예는 다음과 같습니다: * 다음 주에 제인과 최신 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` 루프)를 사용하세요: 각 평가 작업마다 하나의 루프를 구성합니다. 각 평가 에이전트에는 단일 작업 프롬프트와 도구 목록을 제공해야 합니다.

평가 에이전트의 시스템 프롬프트에서는 구조화된 응답 블록(검증용)뿐만 아니라 추론 및 피드백 블록도 출력하도록 지시하는 것이 좋습니다. 도구 호출 및 응답 블록 _이전_에 이러한 블록을 출력하도록 지시하면 사슬형 사고(CoT) 행동을 유발하여 LLM의 효과적인 지능을 높일 수 있습니다.

Claude로 평가를 실행하는 경우, 유사한 기능을 "기본 제공"으로 활용하기 위해 [인터리브드 싱킹](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#interleaved-thinking)을 활성화할 수 있습니다. 이는 에이전트가 특정 도구를 호출하거나 호출하지 않는 이유를 파악하고, 도구 설명 및 사양의 구체적인 개선 영역을 강조하는 데 도움이 됩니다.

최상위 정확도 외에도 개별 도구 호출 및 작업의 총 실행 시간, 총 도구 호출 횟수, 총 토큰 소비량, 도구 오류 등 다른 지표도 수집할 것을 권장합니다. 도구 호출 추적은 에이전트가 수행하는 일반적인 워크플로를 파악하고 도구를 통합할 기회를 제공할 수 있습니다.

![이 그래프는 사람이 작성한 Asana MCP 서버와 Claude가 최적화한 서버의 테스트 세트 정확도를 측정합니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F3f1f47e80974750cd924bc51e42b6df1ad997fab-1920x1080.png&w=3840&q=75) 내부 Asana 도구의 홀드아웃 테스트 세트 성능

결과 분석 에이전트는 도구 설명의 모순부터 비효율적인 도구 구현, 혼란스러운 도구 스키마에 이르기까지 모든 문제점을 발견하고 피드백을 제공하는 유용한 파트너입니다. 그러나 에이전트가 피드백과 응답에서 생략하는 내용이 포함된 내용보다 더 중요할 수 있다는 점을 명심하세요. 대규모 언어 모델(LLM)은 항상 [의도한 바를 정확히 표현하지는 않습니다](https://www.anthropic.com/research/tracing-thoughts-language-model).

에이전트가 막히거나 혼란스러워하는 지점을 관찰하세요. 평가 에이전트의 추론과 피드백(또는 CoT)을 꼼꼼히 읽어 미흡한 부분을 파악하세요. 원본 대화록(도구 호출 및 응답 포함)을 검토하여 에이전트 CoT에 명시되지 않은 행동을 포착하세요. 행간을 읽어보세요; 평가 에이전트가 반드시 정답과 전략을 알고 있는 것은 아니라는 점을 기억하세요.

도구 호출 지표를 분석하세요. 중복된 도구 호출이 많다면 페이지네이션이나 토큰 제한 매개변수의 적절한 조정이 필요할 수 있습니다. 잘못된 매개변수로 인한 도구 오류가 많다면 도구에 더 명확한 설명이나 예시가 필요할 수 있습니다. Claude의 [웹 검색 도구](https://www.anthropic.com/news/web-search) 출시 당시, Claude가 불필요하게 `query` 매개변수에 `2025`를 추가하여 검색 결과를 왜곡하고 성능을 저하시키는 문제를 발견했습니다(도구 설명을 개선하여 Claude를 올바른 방향으로 유도했습니다).

### 에이전트와의 협업
 
에이전트가 결과를 분석하고 도구를 개선하도록 할 수도 있습니다. 평가 에이전트의 대화록을 연결하여 Claude Code에 붙여넣기만 하면 됩니다. Claude는 대화록 분석과 다수 도구 리팩토링에 능숙합니다. 예를 들어, 새로운 변경 사항이 적용될 때 도구 구현과 설명이 자체적으로 일관성을 유지하도록 보장합니다.

사실 이 글의 대부분의 조언은 Claude Code로 내부 도구 구현을 반복적으로 최적화한 결과물입니다. 평가 환경은 실제 프로젝트, 문서, 메시지를 포함한 내부 워크플로의 복잡성을 반영한 내부 작업 공간 위에 구축되었습니다. "훈련" 평가에 과적합되지 않도록 별도로 보관한 테스트 세트를 활용했습니다. 이 테스트 세트는 "전문가" 도구 구현(연구진이 수동으로 작성했든 Claude가 직접 생성했든)으로 달성한 성능을 넘어 추가적인 개선이 가능함을 보여주었습니다. 다음 섹션에서는 이 과정에서 얻은 몇 가지 교훈을 공유하겠습니다. 


## 효과적인 도구 작성 원칙 


이 섹션에서는 효과적인 도구 작성을 위한 몇 가지 핵심 원칙으로 우리의 학습 내용을 정리합니다.

### 에이전트에 적합한 도구 선택

더 많은 도구가 항상 더 나은 결과를 보장하지는 않습니다. 우리가 관찰한 흔한 오류는 기존 소프트웨어 기능이나 API 엔드포인트를 단순히 감싸는 도구들입니다—해당 도구가 에이전트에 적합한지 여부와 무관하게 말이죠. 이는 에이전트가 기존 소프트웨어에 대해 독특한 "어포던스(affordance)"를 지니기 때문입니다. 즉, 에이전트는 해당 도구로 수행할 수 있는 잠재적 행동을 인식하는 방식이 다릅니다

LLM 에이전트는 제한된 "컨텍스트"(즉, 한 번에 처리할 수 있는 정보량에 한계가 있음)를 가지는 반면, 컴퓨터 메모리는 저렴하고 풍부합니다. 주소록에서 연락처를 검색하는 작업을 생각해 보세요. 기존 소프트웨어 프로그램은 연락처 목록을 효율적으로 저장하고 처리하며, 하나씩 확인한 후 다음으로 넘어갈 수 있습니다.

그러나 LLM 에이전트가 모든 연락처를 반환하는 도구를 사용한 후 토큰 단위로 하나씩 읽어내야 한다면, 제한된 컨텍스트 공간을 관련 없는 정보에 낭비하는 셈이다(주소록에서 연락처를 찾을 때 각 페이지를 위에서 아래로 일일이 읽는 방식, 즉 무차별 대입 검색을 상상해 보라). 에이전트와 인간 모두에게 더 우수하고 자연스러운 접근법은 먼저 관련 페이지로 건너뛰는 것입니다(예: 알파벳순으로 찾는 방식). 평가 과제에 부합하는 특정 고효율 워크플로를 대상으로 몇 가지 신중한 도구를 구축한 후 이를 확장해 나가는 것을 권장합니다. 주소록 사례에서는 `list_contacts` 도구 대신 `search_contacts` 또는 `message_contact` 도구를 구현할 수 있습니다.

도구는 기능을 통합하여 내부적으로 잠재적으로 여러 개의 개별 작업(또는 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` 열거형 매개변수를 노출하여 두 가지 모두를 활성화할 수 있습니다. 이를 통해 에이전트가 도구가 `“concise”` 또는 `“detailed”` 응답을 반환할지 제어할 수 있습니다(아래 이미지 참조). GraphQL에서 원하는 정보 조각을 정확히 선택할 수 있는 것과 유사하게, 더 큰 유연성을 위해 더 많은 형식을 추가할 수 있습니다. 도구 응답의 상세도를 제어하는 ResponseFormat 열거형 예시는 다음과 같습니다: 


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


``` 


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


![이 코드 스니펫은 자세한 도구 응답의 예시를 보여줍니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F5ed0d30526bf68624f335d075b8c1541be3bb595-1920x1006.png&w=3840&q=75)

다음은 간결한 도구 응답의 예입니다 (72 토큰): 


![이 코드 스니펫은 간결한 도구 응답을 묘사합니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fd4f649a66482efb5a80cf14ea85e84974ede1c49-1920x725.png&w=3840&q=75)

슬랙 스레드와 스레드 답글은 고유한 `thread_ts`로 식별되며, 스레드 답글을 가져오려면 이 값이 필요합니다. `thread_ts` 및 기타 ID(`channel_id`, `user_id`)는 `“detailed”` 도구 응답에서 가져올 수 있으며, 이를 필요로 하는 추가 도구 호출을 가능하게 합니다. `“concise”` 도구 응답은 스레드 콘텐츠만 반환하며 ID를 제외합니다. 이 예시에서는 `“concise”` 도구 응답으로 토큰의 약 ⅓만 사용합니다. XML, JSON, 마크다운 등 도구 응답 구조 자체도 평가 성능에 영향을 미칠 수 있습니다: 만능 해결책은 없습니다. 이는 LLM이 다음 토큰 예측으로 훈련되어 훈련 데이터와 일치하는 형식에서 더 나은 성능을 보이기 때문입니다. 최적의 응답 구조는 작업과 에이전트에 따라 크게 달라집니다. 자체 평가를 바탕으로 가장 적합한 응답 구조를 선택하시길 권장합니다. 


### 토큰 효율성을 위한 도구 응답 최적화 컨텍스트 품질 


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

많은 컨텍스트를 소모할 수 있는 도구 응답에는 페이지 매김, 범위 선택, 필터링 및/또는 트렁케이션을 합리적인 기본 매개변수 값과 함께 조합하여 구현할 것을 권장합니다. Claude Code의 경우 도구 응답을 기본적으로 25,000 토큰으로 제한합니다. 에이전트의 효과적인 컨텍스트 길이는 시간이 지남에 따라 증가할 것으로 예상되지만, 컨텍스트 효율적인 도구의 필요성은 지속될 것입니다.

응답을 잘라내기로 선택했다면, 유용한 지침으로 에이전트를 유도하세요. 지식 검색 작업 시 단일 광범위 검색 대신 작고 목표 지향적인 검색을 여러 번 수행하는 등, 토큰 효율적인 전략을 직접 권장할 수 있습니다. 마찬가지로, 도구 호출 시 오류가 발생하면(예: 입력 검증 중), 불투명한 오류 코드나 트레이스백 대신 구체적이고 실행 가능한 개선 사항을 명확히 전달하도록 오류 응답을 프롬프트 엔지니어링할 수 있습니다.

다음은 잘린 도구 응답의 예시입니다: 


![이 이미지는 잘린 도구 응답의 예시를 보여줍니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Fe440d6a69d0ca80e71f3bec5c2d00906ff03ce6d-1920x1162.png&w=3840&q=75)

다음은 도움이 되지 않는 오류 응답의 예입니다. 


![이 이미지는 도움이 되지 않는 도구 응답의 예를 보여줍니다. ](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F2445187904704fec8c50af0b950e310ba743fac2-1920x733.png&w=3840&q=75) 


다음은 유용한 오류 응답의 예시입니다: 


![이 이미지는 유용한 오류 응답의 예시를 보여줍니다.](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F810661bd44a35fb273806ae95160040155978c3e-1920x850.png&w=3840&q=75)

도구 절단 및 오류 응답은 에이전트가 더 토큰 효율적인 도구 사용 행동(필터 또는 페이지 매김 사용)을 하도록 유도하거나 올바르게 형식화된 도구 입력의 예시를 제공할 수 있습니다.

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

이제 도구 개선을 위한 가장 효과적인 방법 중 하나인 도구 설명 및 사양의 프롬프트 엔지니어링을 살펴보겠습니다. 이러한 설명은 에이전트의 컨텍스트에 로드되므로, 종합적으로 에이전트가 효과적인 도구 호출 행동을 하도록 유도할 수 있습니다. 도구 설명과 사양을 작성할 때는 팀의 신입 사원에게 도구를 설명하는 방식을 고려하십시오. 암묵적으로 포함될 수 있는 맥락(특화된 쿼리 형식, 전문 용어 정의, 기반 리소스 간 관계 등)을 명시적으로 드러내세요. 예상 입력값과 출력값을 명확히 기술하고(엄격한 데이터 모델로 강제 적용하여) 모호성을 피하십시오. 특히 입력 매개변수는 모호하지 않게 명명해야 합니다: `user`라는 매개변수 대신 `user_id`로 명명하세요.

평가를 통해 프롬프트 엔지니어링의 효과를 더 확신하며 측정할 수 있습니다. 도구 설명의 사소한 개선조차도 극적인 향상을 가져올 수 있습니다. Claude Sonnet 3.5는 도구 설명을 정밀하게 개선한 후 [SWE-bench Verified](https://www.anthropic.com/engineering/swe-bench-sonnet) 평가에서 최첨단 성능을 달성했으며, 오류율을 획기적으로 줄이고 작업 완료율을 향상시켰습니다.

도구 정의에 대한 기타 모범 사례는 [개발자 가이드](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use#best-practices-for-tool-definitions)에서 확인하실 수 있습니다. Claude용 도구를 개발 중이라면, 도구가 Claude의 [시스템 프롬프트](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use#tool-use-system-prompt)에 동적으로 로드되는 방식에 대한 설명도 함께 읽어보시길 권장합니다. 마지막으로, MCP 서버용 도구를 작성하는 경우 [도구 주석](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)을 통해 어떤 도구가 오픈 월드 접근이 필요하거나 파괴적인 변경을 가하는지 알릴 수 있습니다. 


## 앞으로의 전망

에이전트를 위한 효과적인 도구를 구축하려면, 소프트웨어 개발 관행을 예측 가능하고 결정론적인 패턴에서 비결정론적인 패턴으로 전환해야 합니다. 본 글에서 설명한 반복적이고 평가 중심의 과정을 통해, 도구의 성공 요인에 대한 일관된 패턴을 확인했습니다: 효과적인 도구는 의도적이고 명확하게 정의되며, 에이전트 컨텍스트를 신중하게 활용하고, 다양한 워크플로에서 결합될 수 있으며, 에이전트가 현실 세계의 작업을 직관적으로 해결할 수 있도록 합니다.

앞으로 에이전트가 세계와 상호작용하는 구체적인 메커니즘은 MCP 프로토콜 업데이트부터 기반 LLM 자체의 업그레이드에 이르기까지 진화할 것으로 예상됩니다. 에이전트 도구를 개선하기 위한 체계적이고 평가 중심의 접근법을 통해, 에이전트의 능력이 향상됨에 따라 그들이 사용하는 도구도 함께 진화할 수 있도록 보장할 수 있습니다. 


## 감사의 말

연구팀(Barry Zhang, Zachary Witten, Daniel Jiang, Sami Al-Sheikh, Matt Bell, Maggie Vo), MCP팀(Theodora Chu, John Welsh, David Soria Parra, Adam Jones), 제품 엔지니어링팀(Santiago Seira), 마케팅팀(Molly Vorwerck), 디자인팀(Drew Roper), 응용 AI팀(Christian Ryan, Alexander Bricken)의 동료들이 소중한 기여를 한 가운데 Ken Aizawa가 작성했습니다. 


[^1]: 기본 LLM 자체를 훈련하는 것을 넘어