목차
이 글은 Anthropic 엔지니어링 블로그에 2025년 9월 11일 게재된 “Writing effective tools for agents — with agents” 를 읽고, 내용을 정리한 글입니다. 원문: https://www.anthropic.com/engineering/writing-tools-for-agents
한 줄로 말하면 #
에이전트용 도구는, 사람이 머리로 짜기보다 에이전트에게 다듬게 한 것이 더 잘 동작했다.
어떤 문제를 해결하려 했나 #
getWeather("NYC") 같은 함수를 만들 때, 개발자는 “이 함수가 정확한 결과를 빠르게 반환하면 끝"이라고 생각합니다. 입력이 같으면 출력이 같은 결정론적(deterministic) 세상이에요.
에이전트용 도구는 다릅니다. 같은 도구를 두고 에이전트가 엉뚱하게 호출하거나, 이름을 헷갈리거나, 결과를 잘못 해석합니다. 도구 설계가 좋으면 잘 굴러가고, 나쁘면 에이전트가 무한 루프에 빠집니다.
예시 하나. Slack 메시지 스레드를 가져오는 도구가 있다고 합시다.
버전 A: 메시지마다
thread_ts같은 내부 ID를 다 포함해 206 토큰 반환 버전 B: 메시지 본문만 압축해 72 토큰 반환
에이전트 입장에선, 대부분의 경우 ID가 필요 없습니다. 그런데 버전 A는 매번 토큰을 ⅔ 더 태웁니다. 도구 설계 한 줄 차이로 컨텍스트가 빠르게 소진됩니다.
이 글은 “에이전트용 도구는 새 종류의 소프트웨어” 라는 관점에서, 좋은 도구를 만드는 법을 정리합니다.
해결책: 에이전트의 입장에서 도구 설계하기 #
1. 도구는 결정론적 시스템과 비결정론적 에이전트의 ‘계약’ #
전통적 함수와 에이전트용 도구의 본질적 차이는 이렇습니다.
| 일반 API 함수 | 에이전트용 도구 | |
|---|---|---|
| 호출자 | 정확히 짜인 코드 | 추론하는 에이전트 |
| 사용 방식 | 명세대로만 호출 | 창의적·실수·오해 다 가능 |
| 메모리 비용 | 거의 무한 | 컨텍스트 창에 제한 |
| 반환값 기준 | 기술적 정확성 | 의미적 명료성 + 토큰 효율 |
핵심 결론: “메모리는 싸지만 컨텍스트는 비싸다.” API는 메모리만 신경 쓰면 되지만, 도구는 에이전트가 토큰을 얼마나 태우게 하느냐까지 책임져야 합니다.
2. 좋은 도구의 다섯 원칙 #
원문이 정리한 핵심 원칙을 간추리면 이렇습니다.
| 원칙 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 도구 선택 | list_all_contacts (다 긁어오기) |
search_contacts(query) (필요한 것만) |
| 네임스페이싱 | search, users_search, proj_s |
asana_search, asana_users_search, asana_projects_search |
| 반환값 | { uuid, 256px_image_url, mime_type } |
{ name, image_url, file_type } |
| 응답 길이 | 항상 풀 응답 | response_format=CONCISE | DETAILED 선택지 |
| 에러 메시지 | 스택트레이스 던지기 | “이 형식으로 다시 시도해보세요"라고 안내 |
가장 효과 큰 한 가지: 도구 설명문(description)을 새로 합류한 팀원에게 인계하듯 자세히 쓰기. 작은 표현 차이가 에이전트 행동을 완전히 바꿉니다. 한 예로 Claude가 검색어에 자꾸 “2025"를 붙이던 문제는, 코드가 아니라 설명문을 다듬어 해결됐습니다.
3. “— with agents” — 에이전트에게 자기 도구를 평가시키기 #
이 글 제목의 핵심입니다. 도구를 다듬는 일 자체를 에이전트에게 맡기는 워크플로입니다.
[1단계] 프로토타입
Claude Code로 빠르게 구현, 로컬 MCP 서버나 Desktop Extension으로 감싸기
[2단계] 평가 (eval)
실제 작업과 비슷한 평가 과제 생성
→ 단순한 작업이 아니라, 도구 여러 번 조합해야 풀리는 과제로
→ 정확도, 실행시간, 토큰 소비, 에러율 측정
[3단계] 에이전트가 분석·개선
평가 트랜스크립트를 Claude에 통째로 넣기
→ "이 도구들의 문제점을 찾고 리팩토링해줘"
→ Claude가 한 번에 여러 도구를 동시에 고침
[4단계] 검증
hold-out 테스트셋으로 과적합 확인원문이 직접 한 말: “Claude는 트랜스크립트를 분석하고 여러 도구를 한꺼번에 리팩토링하는 데 전문가다.” Anthropic 사내 도구를 이 방식으로 다듬어보니, 사람 전문가가 만든 구현보다 더 잘 동작했습니다.
결과 / 효과 #
- Slack 응답 토큰: 206 → 72 토큰 (약 ⅔ 감소)
- Slack/Asana MCP 서버: Claude 최적화 버전이 사람 작성 버전을 정확도에서 능가
- SWE-bench Verified: 도구 설명문 정밀 다듬기로 Claude Sonnet 3.5가 SOTA 달성
- 기본 응답 한계: Claude Code는 도구 응답을 25,000 토큰으로 제한 (그 이상은 잘림)
핵심 결론 #
도구가 잘 안 굴러갈 때 사람들은 본능적으로 “내가 더 신경 써서 짜야 하나?“라고 생각합니다. 이 글의 답은 다릅니다.
“도구가 부실한 건 설계자가 부족해서인 줄 알았는데, 사실은 사람이 에이전트의 입장을 잘 모른다는 게 문제였다.”
에이전트가 자기 도구를 평가하고 다듬는 게 사람이 짠 것보다 낫더라 — 이게 이 글의 가장 인상적인 발견입니다.
내 작업에 적용한다면 #
이 글의 본질은 “도구 다듬는 일을 사용자(=AI)에게 위임하라” 입니다. 데이터 분석, 웹 자동운영 양쪽에 그대로 옮겨갑니다.
시나리오 1 — 일반적인 데이터 분석 과정 #
분석가가 만든 파이썬 헬퍼 함수, CLI 도구, 노트북 매크로 — 이걸 본인이 매일 쓸 때는 문제없지만 자동 파이프라인에 붙이거나 LLM에 호출시키면 한순간에 불편해집니다.
[기존 흐름]
도구 직접 설계 → 본인 기준으로 다듬기 → 끝
→ 다른 사용자/AI가 쓰면 자꾸 막힘
[best practice 적용]
도구 1차 구현
↓
실제 분석 시나리오로 평가셋 만들기
"지난 분기 매출 상위 5개 지역 추출 후 시즌성 분석"
"이상치 제거 후 회귀 모델 정확도 보고"
↓
Claude에게 트랜스크립트 넘기기
"이 함수들 인터페이스에서 헷갈리는 부분 찾고 다듬어줘"
↓
반환값 단순화, 파라미터 이름 명료화, 에러 메시지 친절화핵심: 데이터 분석 도구는 “내가 쓰기 편한 것” 보다 “누가 봐도 한 번에 이해되는 것” 이 결국 더 자주 재사용됩니다. AI에게 평가시키면 본인이 못 보는 사각지대가 드러납니다.
시나리오 2 — 웹 사이트를 자동으로 운영할 때 #
운영 자동화 스크립트와 CLI 도구도 똑같습니다. 만든 사람만 쓸 수 있는 도구는 자동화 한계가 빠르게 옵니다.
[기존 흐름]
deploy.sh, backup.sh 같은 운영 스크립트 직접 만들기
→ 옵션 이름 헷갈림, 에러 메시지 불친절, 출력값 분석 어려움
[best practice 적용]
운영 도구 1차 구현
↓
운영 시나리오 평가셋
"오늘 새벽에 실패한 배포 원인 파악하고 롤백"
"최근 7일치 트래픽 이상 검출 후 알림"
↓
Claude에게 평가 결과 던지기
"이 스크립트 호출 흐름에서 막힌 지점 찾고 인터페이스 개선"
↓
- 명령어 네이밍을 prefix로 통일 (예: site_deploy, site_rollback, site_backup)
- 결과는 사람·AI 둘 다 읽게 의미적 필드로 반환
- 에러는 다음 행동 안내까지 포함핵심: 자동 운영의 신뢰성은 “AI나 다른 운영자가 도구를 처음 봐도 막힘없이 쓸 수 있는가” 로 결정됩니다. 도구 다듬는 일 자체를 Claude에게 맡기면 사람이 못 본 마찰을 빠르게 찾아냅니다.
Anthropic 엔지니어링 블로그를 오래된 순서대로 읽고 정리합니다.
