도구 설계의 예술

Agent로 Agent 도구 최적화하기

도구가 잘 만들어졌는지 가장 잘 아는 건 Agent 자신입니다. 업계에서는 "Agent로 도구 작성 → 평가 실행 → 자동 최적화" 워크플로우를 검증했습니다. 도구 설계를 수작업 튜닝에서 체계적인 반복으로 전환할 수 있습니다.

핵심 아이디어
전통적인 방식: 인간이 도구 작성 → 인간이 테스트 → 인간이 개선. 사이클이 길고 피드백이 느리며 개발자 직관에 의존합니다.
새로운 방식: Claude Code로 도구 작성 → 평가로 자동 측정 → Claude Code가 평가 결과를 읽고 자동 최적화. Agent가 자신의 도구에 대한 프로덕트 매니저가 됩니다.
3단계 워크플로우: Prototype → Evaluate → Optimize
Prototype
Evaluate
Optimize
평가 결과가 불만족스럽다면? 기준을 충족할 때까지 루프를 반복합니다
01

Prototype

Claude Code를 사용하여 도구 프로토타입을 빠르게 생성합니다. 원하는 도구 기능을 설명하고 MCP 도구의 코드 골격을 생성하도록 합니다.
입력: "Jira 도구를 만들어 주세요. issue 생성, issue 목록 조회, issue 상태 업데이트가 가능해야 합니다"

출력: Claude Code가 도구 정의, 파라미터 검증, API 호출 로직을 포함한 완전한 MCP 도구 코드를 생성합니다
02

Evaluate

평가 시스템을 구축하여 도구 성능을 체계적으로 측정합니다. 데이터로 품질을 증명해야 합니다 — "작동하는 것 같다"는 충분하지 않습니다.
평가 차원:
- Agent가 올바른 도구를 선택했는가?
- 파라미터가 올바르게 채워졌는가?
- 반환 결과가 올바르게 해석되었는가?
- 엔드-투-엔드 작업 완료율은 어떠한가?
03

Optimize

Claude Code가 평가 결과를 읽고 실패 원인을 자동으로 분석하여 도구 설명과 구현을 개선하도록 합니다.
Claude Code 분석: "Agent가 23% 케이스에서 search와 list를 혼동했습니다. 설명이 너무 유사했기 때문입니다"

자동 수정: 도구 설명을 재작성하고 구별 설명과 사용 예제를 추가합니다
5가지 도구 설계 원칙
1

올바른 도구 선택: 적을수록 좋습니다

도구를 너무 많이 구현하지 마세요. 인간 개발자가 search를 써야 할지 find를 써야 할지 lookup을 써야 할지 구별하지 못한다면, Agent도 구별하지 못합니다.
원칙: 두 도구의 사용 시나리오가 50% 이상 겹친다면 합치세요. 파라미터가 더 많은 도구 하나가 혼동하기 쉬운 두 도구보다 낫습니다.
2

네임스페이스: 그룹 관리

관련 도구를 접두사로 그룹화하여 Agent가 도구 간의 관계를 한눈에 파악할 수 있게 합니다.
좋은 명명: jira_create_issue / jira_list_issues / jira_update_status
나쁜 명명: create_issue / list_tasks / update
3

의미 있는 컨텍스트 반환

도구가 "success"만 반환하면 안 됩니다. Agent의 다음 단계에 필요한 정보를 반환해야 합니다.
나쁜 예: {"status": "success"}
좋은 예: {"status": "success", "issue_id": "PROJ-123", "url": "https://...", "assignee": "Alice"}
4

Token 효율성: 반환 결과 최소화

대량의 결과는 줄여야 합니다. 1,000개의 레코드를 반환하면 엄청난 Token을 소비하지만 Agent는 처음 10개만 필요합니다.
전략: 요약(통계 정보만 반환), 잘라내기(기본적으로 상위 N개 반환), 페이지네이션(페이지 파라미터 지원), 필터링(조건 지원)
5

도구 설명을 Prompt처럼 엔지니어링

도구 설명은 단순한 문서가 아니라 Prompt의 일부입니다. Agent에게 이 도구를 언제 사용하는지, 더 중요하게는 언제 사용하지 않는지를 알려줘야 합니다.
좋은 설명 템플릿: "[도구명]은 [구체적인 목적]에 사용됩니다. [시나리오 A] 또는 [시나리오 B]가 필요할 때 이 도구를 사용하세요. [시나리오 C]에서는 사용하지 마세요. 그 경우에는 [다른 도구]를 사용하세요. 예시: [구체적인 입력/출력]"
네임스페이스 실전: Agent에게 도구 맵 제공하기

도구 네임스페이스 그룹

jira_ -- 프로젝트 관리
jira_create_issue jira_list_issues jira_update_status jira_add_comment
git_ -- 버전 관리
git_diff git_commit git_log git_create_branch
db_ -- 데이터베이스
db_query db_insert db_update db_schema
네임스페이스의 가치: Agent가 jira_ 접두사가 붙은 도구 그룹을 보면 이 도구들이 관련이 있고 같은 시스템을 조작한다는 것을 즉시 알 수 있습니다. 이는 잘못된 도구를 선택할 확률을 크게 낮춥니다.
Token 효율성: 반환 결과의 학문

전체 반환

[ {"id": 1, "title": "Fix login bug", "desc": "Users cannot login...", "created": "2025-01-15T...", "updated": "2025-01-16T...", "assignee": {"name": "Alice", ...}, "labels": [...], "comments": [...]}, {"id": 2, ...}, ... // 총 847개 레코드 ]
~52,000 Tokens -- Agent가 전혀 처리할 수 없습니다

최소화된 반환

{ "total": 847, "showing": 10, "page": 1, "results": [ {"id": 1, "title": "Fix login", "status": "open", "assignee": "Alice"}, {"id": 2, ...}, ... // 상위 10개, 핵심 필드만 ], "hint": "Use page=2 for more" }
~800 Tokens -- 정보 밀도가 높아 Agent가 쉽게 소화합니다
실제 예시: 도구 설명의 차이

search_issues 도구 설명 비교

BEFORE -- 형식적인 설명
{ "name": "search_issues", "description": "Search for issues in the project tracker." }
Agent는 검색 구문, 반환 형식, list_issues와의 차이점을 알 수 없습니다
AFTER -- 엔지니어링된 설명
{ "name": "search_issues", "description": "Full-text search across issue titles and descriptions. Use when the user mentions specific keywords. Returns max 20 results sorted by relevance. For browsing by status/label, use list_issues instead. Example: search_issues({ query: 'login timeout', status: 'open' })" }
명확한 의미, 사용 경계, 예시, 유사 도구와의 구분이 포함됩니다
최적화 루프의 핵심 인사이트: Claude Code가 평가를 완료한 후 "43%의 오류가 Agent가 search와 list를 혼동했기 때문"이라고 정확히 말할 수 있고, 그 문제를 해결하기 위해 도구 설명을 자동으로 수정합니다. 이는 인간이 직관으로 디버깅하는 것보다 훨씬 빠릅니다.
도구 품질이 Agent 품질의 상한선을 결정합니다. Prototype → Evaluate → Optimize 루프를 사용하여 체계적으로 도구 품질을 향상시키세요. 5가지 원칙을 기억하세요: 올바른 도구 선택, 네임스페이스, 의미 있는 반환, Token 효율성, 엔지니어링된 설명. Agent가 자신의 도구에 대한 프로덕트 매니저가 되게 하세요.