툴 설계 원칙

에이전트에게 줄 툴을 기존 API를 그대로 감싸는 대신, 적은 수의 강한 툴·모호하지 않은 이름·에이전트가 스스로 고칠 수 있는 오류 메시지를 기준으로 다시 설계하는 원칙이다. 기준 시점: 2026-10

왜 필요한가

툴은 사람 개발자가 쓰는 API나 함수와 똑같은 방식으로 만들면 안 된다. 사람은 문서를 찾아가며 필요한 기능만 골라 쓰지만, 에이전트는 매 턴마다 주어진 툴 목록 전체를 컨텍스트에 두고 그중 하나를 골라야 한다. 기존 API 엔드포인트를 그대로 툴로 노출하면 비슷한 기능의 툴이 여러 개 생기고, 에이전트가 어떤 걸 골라야 할지 헷갈리거나(선택 모호성) 한 작업에 툴을 여러 번 나눠 호출하느라 턴을 낭비하게 된다.

설계 원칙

툴 선택과 통합

• 평가 작업(evaluation task)에서 실제로 반복되는 고빈도 워크플로를 기준으로 적은 수의 툴부터 신중하게 만들고, 그 다음에 늘린다.
• 여러 단계로 나뉜 작업은 하나로 합친다. 예를 들어 list_users·list_events·create_event로 나뉜 툴을 가능한 시간을 찾아 일정을 잡아주는 schedule_event 하나로 합치는 식이다.
• list_contacts처럼 전체를 쏟아내는 툴보다 search_contacts·message_contact처럼 목적이 좁은 툴을 선호한다.
• 기능이 겹치는 툴은 만들지 않는다. 겹치는 선택지가 많을수록 에이전트가 효율적인 전략에서 벗어나기 쉬워진다.

이름과 네임스페이스

• 관련 툴은 서비스·리소스 기준 공통 접두사로 묶는다(asana_search, jira_search, asana_projects_search 등).
• 접두사와 접미사 중 어느 쪽이 나은지는 모델마다 다르므로 실제로 테스트해서 정한다.
• 파라미터 이름은 모호하지 않게 짓는다(user보다 user_id).

응답 설계

• name·image_url·file_type처럼 신호가 높은 필드를 돌려주고, UUID·MIME 타입 같은 저수준 식별자는 뺀다.
• 가능하면 사람이 읽을 수 있는 자연어 식별자로 바꿔 돌려준다. UUID를 이름으로 풀어주는 것만으로 환각이 줄고 검색 정밀도가 올라갔다고 한다.
• response_format을 "concise"/"detailed" 같은 enum으로 둬서 에이전트가 필요한 상세도를 고르게 한다. 글에 실린 Slack 예시에서는 concise 응답이 토큰을 약 1/3만 썼다.
• 응답 구조(XML·JSON·Markdown)도 작업과 모델에 따라 최적이 달라지므로 테스트해서 고른다.
• 페이지네이션·범위 선택·필터링·잘림(truncation)에 합리적인 기본값을 둔다. Claude Code는 툴 응답을 기본 25,000토큰으로 제한한다. 응답을 자를 때는 "넓은 검색 한 번" 대신 "작고 구체적인 검색 여러 번"처럼 에이전트가 검색을 좁힐 방법을 함께 안내한다.

오류 메시지

• 알 수 없는 오류 코드나 스택 트레이스 대신, 무엇을 어떻게 고쳐야 하는지 구체적으로 알려준다.
• 필요하면 올바른 입력 형식의 예시를 함께 보여준다.

설명(description)

• 신입 동료에게 설명하듯 쓴다. 질의 형식, 생소한 용어, 리소스 간 관계처럼 암묵적으로 알고 있던 맥락을 전부 명시한다.
• 입력·출력을 명확히 정의하고 엄격한 데이터 모델로 강제한다.
• 설명을 조금만 다듬어도 효과가 크다. Claude Sonnet 3.5가 SWE-bench Verified에서 당시 최고 성능을 낸 데는 이런 설명 다듬기가 있었다고 한다.
• 외부 세계에 접근하거나 되돌릴 수 없는 변경을 하는 툴은 MCP 툴 annotation으로 표시해 둔다.

평가와 테스트

• 로컬 MCP 서버나 Desktop extension으로 툴을 빠르게 만들어 Claude Code·Claude Desktop·API 호출로 직접 테스트해본다.
• 실제 데이터에 기반한 현실적인 평가 작업을 만든다. 좋은 작업은 수십 번의 툴 호출이 필요할 수 있고, 약한 작업은 한 번의 단순 조회로 끝난다.
• 각 작업에 검증 가능한 결과를 짝지어 둔다. 형식이 다르다고 정답을 틀렸다고 판정하는 지나치게 엄격한 검증기는 피하고, 필요하면 LLM 판정자를 쓴다.
• 어떤 툴이나 전략을 써야 하는지 지나치게 못박아 두면(overfitting) 평가가 왜곡된다.
• 간단한 에이전트 루프로 각 평가 작업을 돌리고, 툴을 호출하기 전에 추론과 피드백을 먼저 쓰게 하면 사고 과정이 좋아질 수 있다.
• 정확도·실행 시간·툴 호출 수·토큰 사용량·툴 오류를 추적한다. 같은 호출이 반복되면 툴 통합이나 페이지네이션 조정이 필요하다는 신호이고, 잘못된 파라미터 오류가 자주 나면 설명을 더 명확히 해야 한다는 신호다.
• 트랜스크립트를 꼼꼼히 읽는다. 에이전트가 무엇을 말하지 않았는지도 무엇을 말했는지만큼 중요하다.
• 에이전트에게 트랜스크립트를 분석해 툴을 고치게 시키고, 홀드아웃 테스트셋으로 그 개선이 일반화되는지 확인한다.

핵심 정리

• 툴은 사람을 위한 API 설계 원칙이 아니라, 매 턴 전체 툴 목록을 컨텍스트에 두고 하나를 골라야 하는 에이전트의 특성에 맞춰 설계해야 한다
• 여러 단계로 쪼개진 기능은 통합하고, 겹치는 툴은 없애서 선택 모호성을 줄인다
• 응답은 신호가 높은 필드만 자연어로 돌려주고, 상세도(response_format)와 잘림 기준을 에이전트가 다룰 수 있게 설계한다
• 오류 메시지와 설명(description)은 에이전트가 스스로 고쳐 쓸 수 있을 만큼 구체적이어야 한다
• 툴 설계는 한 번에 끝나지 않고, 실제 평가 작업과 트랜스크립트 분석을 반복하며 다듬어 가는 과정이다

참고

• Anthropic, "Writing effective tools for AI agents"