■ 도구 설계
표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법
왜 배우나 — 시험이 요구하는 것
시험 목표 3.1 도구·에이전트 과잉 설정 · D3 연결 19%Evaluate tool/agent configuration for capability bloat
이 개념으로 푸는 판단 (할 수 있어야 하는 것)
- 3.1② CRM API 20개를 도구 20개로 그대로 붙였더니 비슷한 도구를 번갈아 잘못 부른다 — 더 쪼개나, 합치나? — 도구 모양 정하기 (엔드포인트 1:1 노출 vs 실제 작업 단위로 통합)
- 3.8② 도구 15개·정의 합계 약 1만 2천 토큰, 매 요청에 쓰는 건 3개 — 30~50개가 안 되는데 tool search 를 켜나? — 도구 정의 미리 다 싣기 vs tool search(필요할 때 불러오기)
한눈에
도구는 API 엔드포인트를 그대로 감싸지 않는다. 에이전트가 실제로 하는 **업무 단위**로 만든다. 도구가 많고 겹칠수록 고르기가 흔들리고 정의가 컨텍스트를 먹는다
비유 kubectl 명령 10개를 매번 조합하게 두지 않는다. 업무 단위 deploy.sh 하나로 묶는다
ELI5
공구함에 드라이버가 스무 개 있으면 맞는 걸 고르다 틀려요.
- 자주 하는 일마다 "그 일 하는 공구" 하나면 편해요.
- 공구마다 이름표를 붙이면 헷갈리지 않아요.
- 이름표에 "언제 쓰고 언제 안 쓰는지"도 적어요.
- 공구가 너무 많으면 필요할 때 꺼내 오는 방법을 써요.
개념 설명
원리
에이전트는 사람 개발자가 아니다
- 개발자용 API 는 엔드포인트가 잘게 나뉘어도 괜찮다. 코드는 목록 전체를 공짜로 훑기 때문이다.
- 에이전트는 컨텍스트가 한정돼 있다.
list_contacts가 전부 돌려주면 토큰마다 읽어야 한다. 이것은 낭비다. 그래서 "찾기" 도구가 낫다. - 에이전트는 도구 이름·설명을 읽고 고른다. 도구가 많고 겹칠수록 고르기가 흔들린다. 30~50개를 넘으면 고르기 정확도가 떨어진다.
합치기는 두 가지를 줄인다
- 도구 개수와 설명 길이(= 컨텍스트)가 준다. 여러 단계 호출의 중간 결과를 에이전트 컨텍스트가 아니라 도구 안에서 처리한다.
- 공식 말 : 도구 이름이 일의 자연스러운 나눔을 따르면 실수 위험이 줄어든다.
경계 긋기
- 합쳐도 서비스가 여럿이면 이름이 겹친다(search 가 셋). 그래서 서비스·자원 접두사를 붙인다.
- 설명은 신입에게 설명하듯 쓴다. 언제 안 쓰는지, 무엇을 안 돌려주는지까지 적는다.
응답이 곧 다음 컨텍스트
- 도구 응답은 그대로 다음 턴 입력이 된다. 그래서 긴 응답은 비용과 혼란을 낳는다. 아래처럼 줄인다.
- 핵심 정보(high signal) 필드만 돌려준다
- 페이지로 나눈다
- 자른다
- 짧게/길게를 고르게 한다
규칙과 판단
갈림길
①②③⑤ 헷갈리는 도구 [3.1②] [3.8②]
설명 보강 먼저
목록이 작으면(10개 미만) 설명 보강이 먼저다 (순서는 추론). 설명에는 무엇을 하나, 언제 쓰고 언제 안 쓰나, 파라미터 뜻, 못 돌려주는 것을 적는다. 도구당 최소 3~4문장이다
합치기 + 네임스페이스, 그래도 많으면 tool search 쪽
30~50개를 넘으면 고르기 정확도가 떨어진다. 자세한 것은 ◆ 도구 미리 싣기 vs tool search 에 있다
합치기 + 네임스페이스
도구가 늘면 더 헷갈린다. 합치고 네임스페이스로 구분한다
⑥ eval 증상 [3.1②]
페이지·토큰 한도를 조정한다
중복 호출이 많으면 페이지·토큰 한도를 조정한다
설명·예시를 보강한다
파라미터 오류가 많으면 설명·예시를 보강한다
① 범용 vs 업무 단위 [3.1②]
범용 도구
열린 과제(코딩)에는 조합 가능한 범용 도구를 쓴다 (가르는 해석은 업계 일반)
업무 단위 도구
정해진 업무에는 업무 단위 도구를 쓴다 (가르는 해석은 업계 일반). 둘 다 "엔드포인트마다 좁은 도구 금지" 다
나머지 규칙
-
응답도 설계한다
- 핵심 정보(high signal)만 돌려준다(
uuid·mime_type대신name·file_type) - 긴 응답은 페이지·필터·자르기에 기본값을 둔다
- Claude Code 는 도구 응답 상한이 기본 25,000토큰이다
- 오류는 고칠 방법을 말하는 문장으로 쓴다
response_formatenum(concise/detailed)을 둔다. 공식 예에서는 206 에서 72토큰(약 ⅓)으로 줄었다 - 핵심 정보(high signal)만 돌려준다(
규칙 원문 ①②③⑤⑥ (갈림길로 그린 규칙)
-
도구는 적게, 업무 단위로 합친다 [3.1②]
- list_users·list_events·create_event 는 schedule_event 하나로 합친다 (빈 시간 찾기 + 예약)
- read_logs 는 search_logs 로 바꾼다 (관련 줄과 주변만)
- get_customer_by_id·list_transactions·list_notes 는 get_customer_context 로 합친다
- list_contacts(전부 반환)는 search_contacts 로 바꾼다
- docs 식 : create_pr·review_pr·merge_pr 는
action파라미터를 가진 도구 하나로 합친다
-
이름으로 경계를 긋는다. 이것이 네임스페이스(namespacing)다. 서비스·자원 접두사를 붙인다(asana_search·jira_search / asana_projects_search). 접두와 접미는 모델마다 효과가 달라 eval 로 고른다
-
설명이 제일 큰 lever(조절 수단)다. 설명에는 아래 넷을 적는다. 도구당 최소 3~4문장이다
- 무엇을 하나
- 언제 쓰고 언제 안 쓰나
- 파라미터 뜻
- 못 돌려주는 것
파라미터 이름은 모호하지 않게 짓는다(
user대신user_id)합치기와 설명 고치기는 다르다. 도구 기능이 겹치거나 목적이 모호하면 에이전트가 헷갈린다
합쳐도 설명이 모호한 채면 헷갈림은 그대로다. 목록이 작으면(10개 미만) 설명 보강이 먼저다 (순서는 추론)
-
개수 문턱 : 30~50개를 넘으면 고르기 정확도가 떨어진다. 합쳐도 많으면 ◆ 도구 미리 싣기 vs tool search 로 간다
-
고치는 순서 : 아래 차례로 고친다
- 프로토타입을 만든다
- 실제 업무 같은 eval 과제(도구를 여러 번 부르는)를 돌린다
- transcript·호출 수·오류를 보고 고친다
- 따로 떼어 둔(held-out) 평가 세트로 과적합을 확인한다
중복 호출이 많으면 페이지·토큰 한도를 조정한다. 파라미터 오류가 많으면 설명·예시를 보강한다
더 깊이 : 판단 규칙 · 상황 변수 (설명)
판단 규칙
| 조건 | 답 | 근거 |
|---|---|---|
| API 엔드포인트마다 도구가 하나다. 비슷한 도구를 번갈아 잘못 부른다 | 업무 단위로 합치고 네임스페이스로 구분한다 | writing-tools · define-tools |
| 도구가 전부를 돌려준다(list_*) | 찾기·거르기 도구로 바꾼다(search_*) | writing-tools |
| 여러 호출을 자주 이어 부른다 | 도구 하나가 안에서 처리한다 | writing-tools "handle frequently chained, multi-step tasks in a single tool call" |
| 여러 서비스에 같은 이름의 도구가 있다 | 서비스(·자원) 접두사를 붙인다 | writing-tools · define-tools |
| 설명이 한 줄뿐이다 | 무엇·언제(안)·파라미터·못 돌려주는 것을 3~4문장 이상 쓴다 | define-tools |
| 응답이 길어 컨텍스트를 먹는다 | 페이지·범위·필터·자르기에 기본값을 둔다. response_ 을 쓴다 | writing-tools |
| 합쳐도 30~50개를 넘는다 | tool search 를 쓴다 | tool-search-tool · ◆ 도구 미리 싣기 vs tool search |
| 어떤 방식이 나은지 모른다(접두 vs 접미 · 응답 형식) | 자기 eval 로 고른다 | writing-tools |
상황 변수
| 변수 | 값 | 답 쪽 | 등급 | 근거 |
|---|---|---|---|---|
| 도구 개수 | 한 자리이고 겹침이 없다 | 그대로 둬도 된다 | 업계 일반 | — |
| 도구 개수 | 30~50 을 넘는다 | 합치고 tool search 를 쓴다 | tool-search-tool | |
| 증상 | 비슷한 도구 사이에서 잘못 고른다 | 합치거나, 이름을 바꾸거나, 경계 문장을 쓴다 | writing-tools | |
| 증상 | 같은 도구를 중복 호출한다 | 페이지·토큰 한도를 조정한다 | writing-tools | |
| 증상 | 파라미터 오류가 잦다 | 설명·예시(input_)를 보강한다 | writing-tools · define-tools | |
| 과제 모양 | 열린 과제(코딩처럼 단계가 미리 안 정해진다) | 조합 가능한 범용 도구를 쓴다 | (Skilljar) | Skilljar API 287803 "reasonably abstract tools" |
| 과제 모양 | 정해진 업무 흐름(예약·고객 조회) | 업무 단위 통합 도구를 쓴다 | writing-tools | |
| 권한 경계 | 합칠 동작끼리 권한이 다르다(읽기 vs 머지) | 나누거나 실행 전에 검사한다 | 업계 일반 | ■ 최소 권한 뒤집히는 때 4 |
연습 문제
상담 에이전트에 CRM API 엔드포인트마다 도구를 하나씩, 24개를 붙였다. get_customer_by_id · list_transactions · list_notes 처럼 비슷한 도구를 번갈아 잘못 부른다겹치는 도구. 실제 상담 업무 단위로 묶으면 8개쯤으로 줄어든다합치면 적음. 팀은 도구를 더 쪼개고 설명을 길게 쓰자고 한다. 무엇을 할까?
시험 대비
함정
- "비슷한 도구를 번갈아 잘못 부르니 엔드포인트마다 더 쪼개고 설명을 길게 쓴다" 는 함정이다. 도구가 늘면 더 헷갈린다. 합치고 네임스페이스로 구분한다
- "작게 쪼갤수록 재사용·권한 관리에 좋다(유닉스 철학)" 는 함정이다. 에이전트는 컨텍스트가 한정돼 있다. 전부 돌려주는 list_* 는 낭비다
- "모든 걸 하는 mega tool 하나로 만든다" 는 함정이다. 공식은 "목적이 뚜렷한 도구를 업무 단위로"까지만 말한다. 하나로 몰 근거는 없다 (목록 영상 요령이고 공식 근거는 없다)
- "더 큰 모델로 바꾸면 덜 헷갈린다" 는 함정이다. 모델은 이름·설명을 보고 고른다. 경계부터 긋는다 업계 일반 CCA-F 노트 2.1 같은 함정
- Skilljar 는 "hyper-specialized 말고 reasonably abstract 한(bash·read 같은 범용) 도구"를 권한다. 합치기와 반대 같지만 둘 다 "엔드포인트마다 좁은 도구 금지" 다. 열린 과제(코딩)에는 조합 가능한 범용 도구를, 정해진 업무에는 업무 단위 도구를 쓴다 (가르는 해석은 업계 일반)
신호
"More tools don’t always lead to better outcomes."
"Instead of implementing a list_users, list_events, and create_event tools, consider implementing a schedule_event tool which finds availability and schedules an event."
"Too many tools or overlapping tools can also distract agents from pursuing efficient strategies."
"Namespacing (grouping related tools under common prefixes) can help delineate boundaries between lots of tools"
"Consolidate related operations into fewer tools." (docs define-tools)
"Claude's ability to pick the right tool degrades once you exceed 30–50 available tools." (docs tool-search)
"The key insight for building effective agents is providing reasonably abstract tools rather than hyper-specialized ones." (Skilljar)
더 깊이 : 뒤집히는 때 · 오답 재료 (설명)
뒤집히는 때
1. 합치기가 최소 권한(least privilege)과 부딪히는 때
- 조건 :
ticket도구 하나에action= read·draft·refund 를 합쳤다. 상담원 역할은 read·draft 만 한다. - 판단 : 합친 도구를 주면 refund 도 따라온다. 권한 경계가 다른 동작은 합치지 말고 나눠 둔다. 그래야 "역할에 필요 없는 도구 제거"가 가능하다.
- 등급 : 업계 일반 (공식 권고 둘을 같이 쓸 때의 추론)
- 근거 : define-tools · 가이드 샘플 1
2. 범용 도구가 맞는 때
- 조건 : 코딩·리서치처럼 단계를 미리 못 정하는 에이전트다.
- 판단 : 업무 단위 도구를 미리 다 만들 수 없다. bash·read·edit 같은 범용·조합 가능 도구가 공식(Skilljar)이 드는 모양이다. 둘 다 "엔드포인트마다 좁은 도구"는 거부한다.
- 등급 : (Skilljar 문장) · 가르는 기준은 업계 일반
- 근거 : Skilljar API 287803 · writing-tools "subdivide and solve tasks in much the same way that a human would"
3. 응답을 줄이면 얼마나 아끼나
- 조건 : 스레드 조회 도구가 한 작업에서 25번 불린다.
- 계산 : 공식 예는 detailed 206토큰, concise 72토큰이다. 25번이면 5,150 대 1,800토큰이다. 차이 3,350토큰이 매 턴 뒤쪽 입력에 쌓인다.
- 전제 : 호출마다 응답 크기가 공식 예와 같다고 본다. concise 는 ID 가 필요한 후속 호출이 없을 때만 쓴다.
- 등급 : 계산
- 근거 : writing-tools
4. 설명을 길게 쓰는 게 답이 되는 때
- 조건 : 도구는 이미 적고 겹치지 않는다. 그런데 파라미터를 자꾸 틀리게 채운다.
- 판단 : 이때는 합치기·쪼개기가 아니라 설명·예시 보강이 답이다. "더 길게 설명" 보기가 오답인 것은 도구를 늘리며 설명으로 구분하려 할 때다.
- 근거 : writing-tools · define-tools
오답 재료
| 오답 | 왜 끌리나 | 왜 틀리나 | 등급 | 근거 |
|---|---|---|---|---|
| "엔드포인트마다 도구를 더 세분하고 설명을 길게" | 정밀해 보인다 | 도구가 늘면 겹침과 고르기 부담이 커진다 | writing-tools | |
| "API 20개를 도구 20개로 1:1 노출이 정석" | 기존 API 를 재사용할 수 있다 | "기존 API 를 감싸기만 한 도구"가 공식이 꼽은 흔한 실수다 | writing-tools | |
| "모든 기능을 하는 mega tool 하나" | 도구 수가 최소다 | 공식은 목적이 뚜렷한 도구를 업무 단위로 만들라고 한다. 하나로 몰 근거는 없다 | 업계 일반 | 목록 3.1② 영상 메모 |
| "list_all 로 다 주고 모델이 고르게" | 모델이 알아서 찾을 것 같다 | 한정된 컨텍스트를 낭비한다. 찾기 도구로 바꾼다 | writing-tools | |
| "더 큰 모델로 바꾼다" | 고르기를 지능 문제로 본다 | 원인은 겹치는 이름·설명이다 | 업계 일반 | CCA-F 노트 2.1 |
| "도구 응답은 전부 돌려줘야 정확" | 정보 손실이 두렵다 | 핵심 정보만 돌려준다. 필요하면 detailed 를 고른다 | writing-tools | |
| "UUID 를 그대로 돌려준다" | 식별자가 정확하다 | 뜻 있는 이름과 0부터 매긴 번호가 환각(hallucination)을 줄인다 | writing-tools |
참고
더 깊이 : CCA-F · 출처 · 상태 · 미해결 (참고)
CCA-F
겹침 — CCA-F 는 "설명이 겹쳐 엉뚱한 도구가 불림 → 개명 + 경계 문장"(설명 고치기)을 물었다. 여기서는 **도구 모양 자체**(엔드포인트 1:1 vs 업무 단위 통합)를 설계 판단으로 묻는다. 오답은 "더 쪼개기" 다
출처
- 가이드 목표 3.1 공식 시험 가이드 v1.0
- writing-tools-for-agents
- define-tools
- tool-search-tool
- mcp-connector
- Skilljar API 287803
- CCA-F 노트 2.1 (개인 학습 노트)
상태
- 업계 일반 3줄
미해결
- 목록 3.1② "도구가 많으면 정의가 컨텍스트를 먹는다"의 구체 숫자(서버 5개 약 5만 5천 토큰)는 tool-search 문서에 있다. 본문은 ◆ 도구 미리 싣기 vs tool search 카드 몫이라 여기에 옮기지 않는다.
- 목록 영상 요령 "mega tool 은 오답"은 공식 근거가 없다(목록 자체 메모와 같다).
- 접두 vs 접미 네임스페이스 중 무엇이 나은지는 공식이 "모델마다 다름, eval 로"라고만 한다. 시험이 한쪽을 정답으로 박으면 근거가 약하다.