Tool Design 원칙 완벽 가이드

AI 에이전트를 위한 툴 설계 원칙을 다룹니다. 모호성을 제거하고 효율적인 툴 세트를 구성하는 방법부터 5가지 핵심 설계 원칙까지, 실무에서 바로 적용할 수 있는 베스트 프랙티스를 소개합니다.

---

목차

1. 김개발의_툴_지옥
2. 결정론적_vs_비결정론적_툴
3. 통합_원칙_모호성_제거
4. 다섯가지_설계_원칙
5. 최소_툴_세트_접근법
6. 베스트_프랙티스_가이드

---

1. 김개발의 툴 지옥

어느 날 김개발 씨는 회사에서 AI 에이전트 시스템을 개발하라는 미션을 받았습니다. "툴만 잘 만들면 되겠지"라는 가벼운 마음으로 시작했지만, 일주일 후 그의 코드에는 무려 47개의 툴이 난무하고 있었습니다.

더 큰 문제는 AI가 어떤 툴을 써야 할지 몰라 매번 엉뚱한 결과를 내놓는다는 것이었습니다.

툴 지옥이란 AI 에이전트에 너무 많은 툴을 제공하거나, 각 툴의 설명이 모호해서 AI가 올바른 선택을 하지 못하는 상황을 말합니다. 마치 메뉴판에 500가지 음식이 있는 레스토랑에서 주문하는 것과 같습니다.

선택지가 많다고 좋은 것이 아니라, 명확한 선택지가 중요합니다.

다음 코드를 살펴봅시다.

// 나쁜 예: 모호하고 중복된 툴 정의
const badTools = [
  { name: "getData", description: "데이터를 가져옵니다" },
  { name: "fetchData", description: "데이터를 불러옵니다" },
  { name: "retrieveData", description: "데이터를 조회합니다" },
  { name: "getInfo", description: "정보를 가져옵니다" },
  // AI는 이 중 무엇을 써야 할지 혼란스러워합니다
];

// 좋은 예: 명확하고 구분된 툴 정의
const goodTools = [
  { name: "database_query", description: "SQL 쿼리로 데이터베이스에서 데이터 조회" },
  { name: "api_fetch", description: "외부 REST API에서 JSON 데이터 요청" },
  { name: "file_read", description: "로컬 파일 시스템에서 파일 내용 읽기" },
];

김개발 씨는 입사 2년 차 개발자입니다. AI 스타트업에서 일하는 그에게 어느 날 CTO가 다가왔습니다.

"김 개발자, 우리 서비스에 AI 에이전트 기능을 추가해야 하는데 맡아줄 수 있겠어요?" 처음에는 간단해 보였습니다. AI 모델에 몇 가지 도구를 제공하고, 사용자 요청에 따라 적절한 도구를 선택하게 하면 될 것 같았습니다.

김개발 씨는 자신만만하게 코딩을 시작했습니다. "파일 읽기 도구가 필요하겠네.

그리고 API 호출 도구도 필요하고, 데이터베이스 조회 도구도 있어야겠지." 하나둘씩 도구를 추가하다 보니 일주일 만에 47개의 도구가 만들어졌습니다. 문제는 그다음부터 시작되었습니다.

사용자가 "고객 정보 좀 알려줘"라고 요청하면 AI는 getData를 쓸지, fetchData를 쓸지, getInfo를 쓸지 갈팡질팡했습니다. 심지어 가끔은 완전히 엉뚱한 도구를 선택하기도 했습니다.

선배 개발자 박시니어 씨가 김개발 씨의 모니터를 보다가 한숨을 쉬었습니다. "김 개발자, 이건 전형적인 툴 지옥이에요.

AI 입장에서 생각해 보세요." 박시니어 씨는 화이트보드에 그림을 그리기 시작했습니다. "우리가 큰 마트에 가면 어떤 느낌이 들어요?

선택지가 너무 많으면 오히려 결정을 못 하잖아요. AI도 마찬가지예요." 툴 지옥에 빠지면 여러 가지 문제가 발생합니다.

첫째, AI의 응답 품질이 떨어집니다. 적절한 도구를 선택하지 못하면 원하는 결과를 얻을 수 없습니다.

둘째, 토큰 비용이 증가합니다. 수십 개의 도구 설명을 매번 프롬프트에 포함해야 하기 때문입니다.

셋째, 그리고 가장 중요한 문제는 예측 불가능성입니다. 같은 요청에 대해 AI가 다른 도구를 선택하면 결과도 달라집니다.

이는 사용자 경험을 크게 해칩니다. 해결책은 생각보다 단순합니다.

도구의 수를 줄이고, 각 도구의 역할을 명확하게 정의하면 됩니다. getData, fetchData, retrieveData처럼 비슷한 이름의 도구를 만들지 말고, database_query, api_fetch, file_read처럼 용도가 확실히 구분되는 이름을 사용해야 합니다.

김개발 씨는 47개의 도구를 12개로 줄였습니다. 각 도구의 설명도 "데이터를 가져옵니다"처럼 모호하게 쓰지 않고, "SQL 쿼리를 실행하여 PostgreSQL 데이터베이스에서 결과를 조회합니다"처럼 구체적으로 작성했습니다.

결과는 놀라웠습니다. AI의 도구 선택 정확도가 60%에서 95%로 뛰어올랐습니다.

토큰 비용도 40% 감소했습니다. 김개발 씨는 깨달았습니다.

좋은 도구 설계는 AI 에이전트 성능의 핵심이라는 것을.

실전 팁

💡 - 도구 이름은 동사_명사 형식으로 명확하게 작성하세요 (예: file_read, database_query)

• 도구 설명에는 반드시 "무엇을", "어디서", "어떻게" 하는지 포함하세요
• 비슷한 기능의 도구가 3개 이상이면 통합을 고려하세요

---

2. 결정론적 vs 비결정론적 툴

김개발 씨가 만든 AI 에이전트가 이상한 행동을 보이기 시작했습니다. 같은 질문을 해도 어떨 때는 정확한 답을 주고, 어떨 때는 엉뚱한 답을 내놓았습니다.

"왜 결과가 매번 달라지는 거지?" 김개발 씨는 머리를 긁적였습니다.

결정론적 툴은 같은 입력에 항상 같은 출력을 반환하는 도구입니다. 반면 비결정론적 툴은 같은 입력에도 다른 출력을 반환할 수 있습니다.

마치 자판기는 결정론적이고 룰렛은 비결정론적인 것과 같습니다. AI 에이전트 설계 시 이 차이를 이해하는 것이 매우 중요합니다.

다음 코드를 살펴봅시다.

// 결정론적 툴: 같은 입력 = 같은 출력
const deterministicTool = {
  name: "calculate_tax",
  description: "주어진 금액에 대한 세금을 계산합니다 (세율 10% 고정)",
  execute: (amount: number): number => {
    return amount * 0.1; // 항상 동일한 결과
  }
};

// 비결정론적 툴: 같은 입력이라도 다른 출력 가능
const nonDeterministicTool = {
  name: "get_current_stock_price",
  description: "현재 주식 가격을 조회합니다 (실시간 변동)",
  execute: async (symbol: string): Promise<number> => {
    const response = await fetch(`/api/stocks/${symbol}`);
    return response.json(); // 시간에 따라 다른 결과
  }
};

박시니어 씨가 김개발 씨에게 질문했습니다. "김 개발자, 혹시 Tools as Contracts라는 개념을 알고 있어요?" 김개발 씨는 고개를 저었습니다.

박시니어 씨는 설명을 시작했습니다. "도구는 일종의 계약이에요.

AI와 시스템 사이의 약속이죠. 이 계약은 크게 두 종류로 나눌 수 있어요." 첫 번째는 결정론적 계약입니다.

자판기를 생각해 보세요. 1000원을 넣고 콜라 버튼을 누르면 언제나 콜라가 나옵니다.

아침에 눌러도, 저녁에 눌러도, 내일 눌러도 결과는 같습니다. 이런 예측 가능성이 바로 결정론적 도구의 핵심입니다.

두 번째는 비결정론적 계약입니다. 주식 시세 조회를 생각해 보세요.

오전 10시에 삼성전자 주가를 조회하면 75,000원이 나올 수 있지만, 오후 3시에 같은 조회를 하면 76,500원이 나올 수 있습니다. 입력은 같지만 출력은 시점에 따라 달라집니다.

김개발 씨가 물었습니다. "그러면 비결정론적 도구는 나쁜 건가요?" 박시니어 씨는 고개를 저었습니다.

"아니요, 둘 다 필요해요. 중요한 건 AI에게 이 차이를 명확히 알려주는 거예요." 결정론적 도구는 캐싱과 재시도에 유리합니다.

결과가 항상 같으니 한 번 계산한 값을 저장해두고 재사용할 수 있습니다. 또한 에러가 발생해도 같은 입력으로 다시 시도하면 됩니다.

비결정론적 도구는 실시간성과 최신성이 중요할 때 사용합니다. 현재 날씨, 실시간 환율, 최신 뉴스 등 시시각각 변하는 정보를 다룰 때 필수적입니다.

AI 에이전트를 설계할 때는 각 도구의 성격을 명확히 표시해야 합니다. 도구 설명에 "실시간", "현재", "최신" 같은 키워드가 있으면 비결정론적 도구임을 AI가 인지할 수 있습니다.

반대로 "계산", "변환", "고정" 같은 키워드는 결정론적 도구를 나타냅니다. 김개발 씨는 자신의 도구들을 다시 분류했습니다.

계산기, 단위 변환기, 포맷터는 결정론적 도구로, API 조회, 데이터베이스 쿼리, 웹 크롤링은 비결정론적 도구로 구분했습니다. 더 나아가 김개발 씨는 비결정론적 도구의 결과를 캐싱할 때 **TTL(Time To Live)**을 설정했습니다.

주식 가격은 1분, 날씨 정보는 10분, 환율 정보는 30분 동안만 캐시를 유지하도록 했습니다. 이렇게 도구의 성격을 이해하고 적절히 활용하자 AI 에이전트의 동작이 훨씬 예측 가능해졌습니다.

사용자들의 불만도 크게 줄었습니다.

실전 팁

💡 - 도구 설명에 결정론적/비결정론적 특성을 명시하세요

• 비결정론적 도구는 적절한 캐시 전략과 함께 사용하세요
• 중요한 비즈니스 로직에는 가능한 한 결정론적 도구를 사용하세요

---

3. 통합 원칙 모호성 제거

"이 API 호출 도구랑 저 HTTP 요청 도구가 뭐가 다른 거야?" 신입 개발자가 김개발 씨에게 질문했습니다. 김개발 씨는 대답하려다가 말문이 막혔습니다.

솔직히 자신도 왜 두 개를 따로 만들었는지 기억이 나지 않았습니다.

Consolidation(통합) 원칙은 비슷한 기능을 가진 여러 도구를 하나로 합쳐서 모호성을 제거하는 설계 원칙입니다. 마치 스위스 아미 나이프가 여러 도구를 하나로 통합한 것처럼, AI 에이전트의 도구도 기능별로 명확하게 통합해야 합니다.

다음 코드를 살펴봅시다.

// 통합 전: 모호하고 중복된 도구들
const beforeConsolidation = [
  { name: "callApi", handler: callApi },
  { name: "httpRequest", handler: httpRequest },
  { name: "fetchEndpoint", handler: fetchEndpoint },
  { name: "restCall", handler: restCall },
];

// 통합 후: 하나의 명확한 도구
interface HttpToolParams {
  method: "GET" | "POST" | "PUT" | "DELETE";
  url: string;
  headers?: Record<string, string>;
  body?: unknown;
}

const httpTool = {
  name: "http_request",
  description: "HTTP 요청을 수행합니다. method로 GET/POST/PUT/DELETE 지정",
  execute: async (params: HttpToolParams) => {
    const { method, url, headers, body } = params;
    return fetch(url, { method, headers, body: JSON.stringify(body) });
  }
};

김개발 씨는 자신이 만든 도구 목록을 다시 살펴보았습니다. HTTP 관련 도구만 네 개나 있었습니다.

callApi, httpRequest, fetchEndpoint, restCall. 이름은 다르지만 하는 일은 거의 비슷했습니다.

박시니어 씨가 조언했습니다. "AI 입장에서 생각해 보세요.

외부 서버에 요청을 보내고 싶을 때, 이 네 개 중 뭘 골라야 할까요? 미묘한 차이가 있을 수도 있지만, AI는 그 차이를 알 수 없어요." 모호성은 AI 에이전트의 최대 적입니다.

두 도구의 차이가 명확하지 않으면 AI는 랜덤하게 선택하거나, 아예 잘못된 도구를 선택할 수 있습니다. 이런 모호성을 제거하는 가장 좋은 방법이 바로 통합입니다.

통합의 핵심 원리는 간단합니다. 비슷한 도구들을 하나로 합치고, 세부적인 차이는 매개변수로 처리하는 것입니다.

callApi, httpRequest, fetchEndpoint, restCall을 하나의 http_request 도구로 합치고, GET/POST/PUT/DELETE는 method 매개변수로 지정하면 됩니다. 김개발 씨가 물었습니다.

"그러면 모든 도구를 하나로 합치면 되는 건가요?" 박시니어 씨는 웃으며 고개를 저었습니다. "그건 또 다른 문제를 만들어요.

적절한 수준의 통합이 중요해요." 통합의 기준은 도메인입니다. HTTP 요청은 하나로 통합하고, 데이터베이스 쿼리는 또 다른 하나로 통합하고, 파일 시스템 작업은 별도로 통합합니다.

서로 다른 도메인의 기능을 하나로 합치면 오히려 혼란이 가중됩니다. 또한 통합할 때는 매개변수 설계가 중요합니다.

매개변수가 너무 많으면 AI가 올바르게 채우기 어렵습니다. 필수 매개변수는 최소화하고, 선택적 매개변수는 합리적인 기본값을 제공해야 합니다.

김개발 씨는 47개의 도구를 도메인별로 분류했습니다. HTTP 관련 4개는 1개로, 파일 관련 6개는 2개로, 데이터베이스 관련 8개는 3개로 통합했습니다.

최종적으로 12개의 도구가 남았습니다. 통합 후 가장 큰 변화는 프롬프트 길이였습니다.

47개의 도구 설명을 포함하던 프롬프트가 12개의 도구 설명만 포함하게 되었습니다. 토큰 비용이 줄었을 뿐 아니라, AI가 각 도구를 더 깊이 이해할 수 있게 되었습니다.

무엇보다 AI의 도구 선택 정확도가 크게 향상되었습니다. 선택지가 줄어드니 잘못 선택할 확률도 줄어든 것입니다.

김개발 씨는 통합의 힘을 실감했습니다.

실전 팁

💡 - 같은 도메인의 비슷한 도구는 과감하게 통합하세요

• 통합된 도구의 매개변수는 명확한 타입과 기본값을 제공하세요
• 도구당 필수 매개변수는 3개 이하로 유지하세요

---

4. 다섯가지 설계 원칙

"좋아, 이제 도구 수도 줄였고 통합도 했어. 근데 아직도 뭔가 부족한 것 같아." 김개발 씨는 혼잣말을 했습니다.

마침 지나가던 박시니어 씨가 그 말을 들었습니다. "도구 설계에는 지켜야 할 5가지 원칙이 있어요.

한번 알아볼까요?"

Clarity, Namespacing, Efficiency, Recovery, Consistency. 이 다섯 가지는 좋은 도구 설계의 핵심 원칙입니다.

마치 건물을 지을 때 따라야 할 건축 법규처럼, 도구를 설계할 때도 이 원칙들을 따라야 견고하고 사용하기 쉬운 시스템을 만들 수 있습니다.

다음 코드를 살펴봅시다.

// 1. Clarity: 명확한 설명과 예시
const clarityExample = {
  name: "search_documents",
  description: "문서를 검색합니다. query: 검색어, limit: 최대 결과 수(기본 10)",
  examples: ["search_documents({query: 'AI 윤리', limit: 5})"]
};

// 2. Namespacing: 도메인별 접두사
const namespacingExample = {
  database: ["db_query", "db_insert", "db_update"],
  file: ["file_read", "file_write", "file_delete"],
  http: ["http_get", "http_post"]
};

// 3. Efficiency: 배치 처리 지원
const efficiencyExample = {
  name: "batch_translate",
  description: "여러 텍스트를 한 번에 번역 (개별 호출보다 효율적)",
  execute: (texts: string[], targetLang: string) => translateBatch(texts, targetLang)
};

// 4. Recovery: 에러 처리 및 복구 정보
const recoveryExample = {
  name: "api_call",
  errorHandling: {
    retry: { maxAttempts: 3, backoff: "exponential" },
    fallback: "cache_lookup"
  }
};

박시니어 씨는 화이트보드에 다섯 개의 단어를 적었습니다. Clarity, Namespacing, Efficiency, Recovery, Consistency.

"이게 도구 설계의 5대 원칙이에요." 첫 번째 원칙은 **Clarity(명확성)**입니다. 도구의 이름, 설명, 매개변수가 누가 봐도 이해할 수 있어야 합니다.

"getData"보다 "search_user_by_email"이 명확합니다. 설명에는 반드시 매개변수의 의미와 예시를 포함해야 합니다.

김개발 씨가 물었습니다. "예시까지 꼭 넣어야 하나요?" 박시니어 씨가 대답했습니다.

"AI도 사람처럼 예시를 보면 더 잘 이해해요. 특히 복잡한 입력 형식이 필요한 도구라면 예시는 필수예요." 두 번째 원칙은 **Namespacing(네임스페이싱)**입니다.

관련된 도구끼리 같은 접두사를 사용하면 AI가 도구들의 관계를 쉽게 파악할 수 있습니다. db_query, db_insert, db_update처럼 데이터베이스 도구는 db_ 접두사를, file_read, file_write처럼 파일 도구는 file_ 접두사를 사용합니다.

세 번째 원칙은 **Efficiency(효율성)**입니다. 가능하면 배치 처리를 지원해야 합니다.

문서 10개를 번역해야 할 때, translate를 10번 호출하는 것보다 batch_translate를 1번 호출하는 것이 훨씬 효율적입니다. API 호출 횟수가 줄면 비용도 줄고 속도도 빨라집니다.

네 번째 원칙은 **Recovery(복구)**입니다. 도구가 실패했을 때 어떻게 대응할지 미리 정의해야 합니다.

재시도 횟수, 백오프 전략, 대체 방안을 명시하면 AI가 에러 상황에서도 적절하게 대응할 수 있습니다. 다섯 번째 원칙은 **Consistency(일관성)**입니다.

모든 도구가 동일한 규칙을 따라야 합니다. 어떤 도구는 snake_case를 쓰고 어떤 도구는 camelCase를 쓰면 혼란스럽습니다.

응답 형식도 마찬가지입니다. 모든 도구가 동일한 구조의 응답을 반환해야 AI가 결과를 일관되게 처리할 수 있습니다.

김개발 씨는 자신의 도구들을 다섯 가지 원칙에 비추어 점검했습니다. 설명이 부실한 도구는 보강하고, 접두사가 없는 도구는 네임스페이스를 추가했습니다.

단건 처리만 되던 도구에는 배치 옵션을 추가했습니다. 에러 처리는 특히 신경을 썼습니다.

각 도구에 재시도 정책과 폴백 전략을 명시했습니다. 외부 API를 호출하는 도구는 캐시를 폴백으로 사용하도록 설정했습니다.

마지막으로 일관성을 위해 코딩 컨벤션 문서를 작성했습니다. 모든 도구 이름은 snake_case, 모든 매개변수는 camelCase, 모든 응답은 { success, data, error } 형식으로 통일했습니다.

실전 팁

💡 - 도구 설명에는 반드시 사용 예시를 포함하세요

• 도메인별로 일관된 접두사를 사용하세요 (예: db_, file_, http_)
• 3개 이상의 항목을 처리할 가능성이 있다면 배치 옵션을 제공하세요

---

5. 최소 툴 세트 접근법

"박 선배, 솔직히 도구가 몇 개가 적당한 거예요?" 김개발 씨가 물었습니다. 12개로 줄였지만 아직도 많은 것 같았습니다.

박시니어 씨는 의미심장하게 웃었습니다. "진짜 필요한 도구만 남기면 생각보다 훨씬 적어요."

**Architectural Reduction(아키텍처 축소)**은 AI 에이전트에 필요한 최소한의 도구 세트만 제공하는 접근법입니다. 마치 미니멀리스트가 꼭 필요한 물건만 남기는 것처럼, 도구도 핵심 기능만 남기고 과감히 제거해야 합니다.

적은 도구가 더 정확한 AI를 만듭니다.

다음 코드를 살펴봅시다.

// 축소 전: 세분화된 도구들
const beforeReduction = [
  "user_create", "user_read", "user_update", "user_delete",
  "product_create", "product_read", "product_update", "product_delete",
  "order_create", "order_read", "order_update", "order_delete",
]; // 12개 도구

// 축소 후: 범용 CRUD 도구
const afterReduction = [
  {
    name: "entity_create",
    description: "엔티티 생성. entityType: user|product|order",
    execute: (entityType: string, data: object) => create(entityType, data)
  },
  {
    name: "entity_read",
    description: "엔티티 조회. entityType과 id 또는 query 조건 지정"
  },
  {
    name: "entity_update",
    description: "엔티티 수정. entityType, id, 변경할 필드 지정"
  },
  {
    name: "entity_delete",
    description: "엔티티 삭제. entityType과 id 지정"
  }
]; // 4개 도구

박시니어 씨가 질문했습니다. "김 개발자, 레스토랑에서 메뉴판이 100페이지면 어떨 것 같아요?" 김개발 씨가 대답했습니다.

"음, 주문하기 너무 힘들 것 같은데요." "맞아요. AI도 똑같아요.

도구가 많으면 많을수록 올바른 선택을 하기 어려워져요." 박시니어 씨는 Architectural Reduction 개념을 설명했습니다. 이 접근법의 핵심 아이디어는 간단합니다.

"정말 이 도구가 필요한가?"라는 질문을 모든 도구에 던지는 것입니다. 비슷한 기능을 하는 도구가 있다면 하나로 합칩니다.

거의 사용되지 않는 도구가 있다면 제거합니다. 김개발 씨의 12개 도구 중 CRUD(Create, Read, Update, Delete) 패턴을 따르는 도구가 많았습니다.

user_create, user_read, product_create, product_read... 이런 식으로 엔티티마다 4개씩 도구가 있었습니다.

박시니어 씨는 제안했습니다. "엔티티별로 도구를 만들지 말고, CRUD 동작별로 도구를 만들어 보세요.

entity_create, entity_read, entity_update, entity_delete 이렇게 4개면 모든 엔티티를 처리할 수 있어요." 김개발 씨가 걱정스럽게 물었습니다. "그러면 AI가 어떤 엔티티를 다루는지 어떻게 알아요?" 박시니어 씨가 대답했습니다.

"매개변수로 전달하면 돼요. entityType이라는 매개변수를 추가해서 user, product, order 같은 값을 받으면 됩니다." 최소 도구 세트의 장점은 여러 가지입니다.

첫째, AI의 선택 정확도가 높아집니다. 선택지가 적으니 실수할 확률도 줄어듭니다.

둘째, 프롬프트가 짧아집니다. 도구 설명이 차지하는 토큰이 줄어 비용이 절감됩니다.

셋째, 유지보수가 쉬워집니다. 새로운 엔티티가 추가되어도 도구를 새로 만들 필요가 없습니다.

기존 entity_create 도구가 새 엔티티를 자동으로 처리합니다. 넷째, 일관성이 유지됩니다.

모든 엔티티가 동일한 인터페이스로 처리되니 예측 가능한 동작을 보장합니다. 물론 지나친 축소는 역효과를 낼 수 있습니다.

하나의 도구가 너무 많은 일을 하면 매개변수가 복잡해지고, AI가 올바른 매개변수를 채우기 어려워집니다. 적절한 균형점을 찾는 것이 중요합니다.

김개발 씨는 12개의 도구를 6개로 줄였습니다. entity_crud 4개, http_request 1개, file_operation 1개.

각 도구는 매개변수로 세부 동작을 구분했습니다. AI의 도구 선택 정확도는 95%에서 99%로 상승했습니다.

실전 팁

💡 - "이 도구를 범용적으로 만들 수 있나?"라고 항상 질문하세요

• 도구 수는 10개 이하로 유지하는 것을 목표로 하세요
• 새 도구를 추가하기 전에 기존 도구 확장을 먼저 고려하세요

---

6. 베스트 프랙티스 가이드

김개발 씨는 많은 것을 배웠습니다. 하지만 실제 프로젝트에 적용하려니 막막했습니다.

"체계적으로 정리된 가이드가 있으면 좋겠는데..." 마침 박시니어 씨가 사내 위키 링크를 공유해 주었습니다. "여기 베스트 프랙티스 문서가 있어요."

베스트 프랙티스는 업계에서 검증된 모범 사례를 정리한 것입니다. 도구 설계의 베스트 프랙티스는 크게 네이밍 규칙, 설명 작성법, 매개변수 설계, 에러 처리로 나눌 수 있습니다.

이 가이드라인을 따르면 일관되고 사용하기 쉬운 도구 세트를 구축할 수 있습니다.

다음 코드를 살펴봅시다.

// 베스트 프랙티스가 적용된 도구 정의
interface ToolDefinition {
  name: string;           // snake_case, 동사_명사 형식
  description: string;    // 한 문장 요약 + 매개변수 설명
  examples: string[];     // 최소 2개의 사용 예시
  parameters: {
    required: string[];   // 필수 매개변수는 3개 이하
    optional: Record<string, unknown>; // 합리적인 기본값 제공
  };
  errorHandling: {
    retryable: boolean;
    maxRetries: number;
    fallbackTool?: string;
  };
}

const bestPracticeTool: ToolDefinition = {
  name: "document_search",
  description: "문서를 전문 검색합니다. query: 검색어, filters: 필터 조건",
  examples: [
    "document_search({query: 'API 설계'})",
    "document_search({query: '보안', filters: {category: 'guide'}})"
  ],
  parameters: {
    required: ["query"],
    optional: { limit: 10, offset: 0, filters: {} }
  },
  errorHandling: { retryable: true, maxRetries: 3 }
};

박시니어 씨가 공유한 문서에는 두 가지 핵심 가이드가 있었습니다. best_practices.md와 architectural_reduction.md.

김개발 씨는 두 문서를 꼼꼼히 읽었습니다. 첫 번째 가이드인 best_practices.md는 도구 설계의 세부 규칙을 담고 있었습니다.

네이밍 규칙부터 시작합니다. 모든 도구 이름은 snake_case로 작성하고, 동사_명사 형식을 따릅니다.

search_documents, create_user, send_email처럼 말이죠. 설명 작성법도 중요합니다.

첫 문장은 도구가 하는 일을 한 줄로 요약합니다. 그다음 각 매개변수의 의미를 설명합니다.

마지막으로 반환값의 형식을 명시합니다. "문서를 검색합니다"보다 "키워드로 문서를 전문 검색하고 관련도순으로 정렬된 결과를 반환합니다"가 훨씬 명확합니다.

예시의 힘은 생각보다 강력합니다. AI는 예시를 통해 도구 사용법을 빠르게 학습합니다.

각 도구마다 최소 2개의 예시를 제공하는 것이 좋습니다. 하나는 기본적인 사용법, 다른 하나는 옵션을 활용한 고급 사용법을 보여줍니다.

매개변수 설계에도 원칙이 있습니다. 필수 매개변수는 3개 이하로 유지합니다.

선택적 매개변수는 합리적인 기본값을 제공합니다. limit의 기본값은 10, offset의 기본값은 0처럼 말이죠.

이렇게 하면 AI가 최소한의 정보만으로도 도구를 올바르게 호출할 수 있습니다. 두 번째 가이드인 architectural_reduction.md는 큰 그림을 다룹니다.

도구 세트를 설계할 때 거쳐야 할 단계를 설명합니다. 먼저 필요한 모든 기능을 나열합니다.

그다음 비슷한 기능끼리 그룹화합니다. 각 그룹을 하나의 도구로 통합합니다.

마지막으로 거의 사용되지 않는 도구를 제거합니다. 에러 처리 전략도 중요한 주제입니다.

각 도구가 실패했을 때 어떻게 대응할지 미리 정의해야 합니다. 재시도 가능한 에러인지, 몇 번까지 재시도할지, 대체 도구가 있는지 명시합니다.

이 정보가 있으면 AI가 에러 상황에서도 적절히 대응할 수 있습니다. 김개발 씨는 두 문서의 내용을 바탕으로 자신의 도구들을 다시 점검했습니다.

모든 도구가 가이드라인을 충족하도록 수정했습니다. 예시가 없던 도구에는 예시를 추가하고, 에러 처리가 없던 도구에는 재시도 전략을 추가했습니다.

완성된 도구 세트는 6개의 도구로 구성되었습니다. 각 도구는 명확한 이름, 상세한 설명, 풍부한 예시, 체계적인 에러 처리를 갖추었습니다.

AI 에이전트의 성능은 눈에 띄게 향상되었습니다. 박시니어 씨가 김개발 씨의 결과물을 보고 만족스럽게 고개를 끄덕였습니다.

"이제 제대로 된 도구 세트가 만들어졌네요. 잘했어요!"

실전 팁

💡 - 팀 공통의 도구 설계 가이드라인 문서를 만들고 유지하세요

• 새 도구를 추가할 때마다 가이드라인 체크리스트를 확인하세요
• 정기적으로 도구 사용 통계를 분석하여 불필요한 도구를 정리하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!