도구를 잘 고르는 문제는 이름을 많이 아는 문제가 아니라, 의도·실행 계약·권한을 서로 다른 시점에 확인하는 문제입니다. 이 글은 먼저 후보를 찾고, 필요한 schema와 Skill 본문을 읽고, 마지막에 실행 권한과 결과 완전성을 검증하는 흐름을 기준으로 삼습니다.
도구 정의의 상시 포함 필요성
수백 개 도구 중 비용 보고서에는 청구 조회·집계·문서 작성만 필요할 수 있습니다.
예를 들어 “이번 달 부서별 지출을 집계해 문서로 남겨라”는 요청은 지출 조회, 집계, 문서 작성 후보를 순서대로 요구할 수 있습니다. discovery가 rename 도구를 찾지 못했다면 이름이 비슷한 삭제·변경 도구를 호출하지 않고, 문서 이름 변경 기능을 찾지 못했다는 경계를 반환해야 합니다. 검색 왕복, 선택한 이름, schema 로딩 성공, 실행 거절을 각각 기록하면 실패 원인을 후보 누락·계약 불일치·권한 거절로 나눌 수 있습니다. 처음에는 작은 도구 목록과 discovery를 제공하고 목표로 후보를 찾은 뒤 상세 schema·예시를 읽습니다. 발견된 이름만 보고 인자를 추측해 실행하지 않습니다. 자주 쓰는 소수는 미리 로딩하고 드문 기능을 지연 로딩할 수 있습니다.
여기서 recall은 실제로 필요한 도구가 후보 목록에 포함된 비율을 뜻하므로, 잘못 섞인 후보 수·모델의 실제 선택·인자 보정 횟수·전체 비용과 함께 측정합니다. 도구 수를 줄이면 모델에 보내는 schema는 작아져도 검색 왕복 비용이 더 커질 수 있고, 드문 자연어 의도나 rename, 서로 비슷한 조회·삭제 도구를 놓칠 수 있습니다. 검색이 실패했을 때는 가장 비슷해 보이는 변경 도구를 대신 실행하지 말고, 필요한 도구를 찾지 못했다는 상태로 보고합니다.
Skills와 가중치 학습·권한 토큰의 구분
파일 기반 Agent Skills는 SKILL.md의 이름·설명·절차와 필요하면 scripts·references·assets를 묶는 재사용 패키지입니다. 메타데이터로 관련성을 판단하고 활성화 때 본문, 세부 작업 때 참고 파일을 읽는 방식이 점진적 로딩입니다. A2A Agent Card가 광고하는 skill과 같은 규약이 아닙니다.
| 층 | 넣을 내용 | 과도한 분할의 문제 |
|---|---|---|
| 이름·설명 | 실제 적용 조건 | 너무 넓으면 오탐 활성화 |
| 본문 | 핵심 절차·금지·검증·중단 | 중요한 조건이 없으면 누락 |
| references | 긴 형식·심화 예제 | 파일 탐색 왕복 증가 |
| scripts | 재사용 변환·검증 | OS·runtime·의존성 차이 |
항상 필요한 금지 조건을 깊은 참고 파일에만 숨기지 않습니다. allowed-tools 같은 메타데이터의 지원은 runtime별로 확인하며 문서가 host의 실행권을 새로 부여하지 않습니다. script도 입력·경로·부수 효과·호환성을 확인해야 합니다.
그림을 글로 읽기
- 현재 목표·부족한 기능
- 후보 도구·스킬 메타데이터
- schema·본문·필요한 참고
- 인가·예산 내 실행
- 검증 결과·원문 참조
- 현재 목표·부족한 기능 → 후보 도구·스킬 메타데이터: 필요성 검색
- 후보 도구·스킬 메타데이터 → schema·본문·필요한 참고: 정확한 계약 읽기
- schema·본문·필요한 참고 → 인가·예산 내 실행: 버전·권한 확인
- 인가·예산 내 실행 → 검증 결과·원문 참조: 누락·오류 포함
대량 집계와 중간 레코드 전송 생략
부서별 지출 10000행을 한 번에 모델에 넣지 않고, 코드가 페이지를 순서대로 읽으며 부서별 합계를 갱신합니다. 각 페이지에서 입력 행 수·통화·필터 결과를 기록하고, 마지막에 초과 부서·전체 입력 수·적용한 필터·통화별 합계·원본 참조만 모델에 돌려줄 수 있습니다. 금액은 최소 단위 정수나 decimal로 계산하며 서로 다른 통화의 금액을 한 합계로 무조건 더하지 않습니다. 마지막 cursor까지 읽었는지, 페이지가 중복되거나 누락되지 않았는지, 일부 페이지에서 오류가 났는지도 함께 기록합니다.
서로 의존하지 않는 조회는 정한 동시성 한도 안에서 병렬로 실행한 뒤, 각 결과를 ID로 결합합니다. 예를 들어 여러 페이지 중 한 페이지가 느려져 실패하면 나머지 합만 전체 합계처럼 표시하지 말고, 해당 페이지 실패 때문에 전체 결과가 불완전하다고 표시합니다. 코드가 변경 도구를 호출하는 경우에도 승인, idempotency, 전체 deadline을 그대로 적용합니다. 재실행할 때는 단계 원장에서 이미 성공한 외부 효과를 확인하고 그 단계는 다시 호출하지 않습니다.
집계 자동화와 의미 보존
단순 숫자 집계는 코드에 적합하지만 복잡한 계약 예외를 키워드 하나로 제거하면 정확성이 달라집니다. 필터 기준·제외 수·오류·입력 범위를 결과에 남깁니다. 모델이 검증된 숫자를 최종 답변에서 임의로 다시 계산해 바꾸지 않게 수치와 설명을 구분합니다.
sandbox 시작·discovery 왕복·API 호출 요금은 남으므로 모델 토큰 감소만으로 더 싸다고 하지 않습니다. 한두 조회에는 일반 도구 호출이 단순할 수 있습니다. 현재 runtime이 프로그램형 호출을 실제 지원하는지도 확인합니다.
정의 변경과 실행 권한의 최종 확인
도구 schema cache에 server·version·인가 범위를 연결합니다. 원격 설명의 “항상 먼저 실행”은 host 정책이 아니며 갱신된 정의가 기존 승인 범위를 넓히지 않습니다. 스킬 선택·없는 도구·잘린 페이지·통화 혼합·반복 실행·권한 철회를 시험합니다. 이 노트는 조합 설계이고 특정 모델의 비용 절감률을 측정한 결과는 아닙니다.