도구 사용(tool use)의 기본 원리를 안다면, 다음 단계는 실제로 안정적으로 동작하게 만드는 것입니다. 이 글은 도구 정의·에러 처리·병렬 호출·결과 포맷에 대한 실무 베스트 프랙티스를 Anthropic 공식 도구 사용 문서 기준으로 정리합니다. (기준 시점: 2026년 6월)
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
1. 도구 정의를 잘 쓰는 법
도구 사용 품질을 좌우하는 가장 큰 요인은 도구 설명(description)입니다. 무엇을 하는 도구인지, 언제 써야 하고 언제 쓰면 안 되는지를 충분히 길고 구체적으로 적을수록 Claude가 올바르게 선택합니다. 파라미터는 input_schema에 필수·선택, 타입, 형식(예: 날짜 포맷)을 명시합니다. 공식 문서는 도구당 설명을 최소 3~4문장 이상 쓰라고 권하며, 중첩 객체나 형식에 민감한 입력이 있는 복잡한 도구에는 설명에 더해 input_examples 필드로 스키마 검증을 거친 예시 입력을 줄 수 있습니다(2026년 9월 문서).
입력이 어긋나면 실패하는 프로덕션 에이전트라면 도구 정의에 strict: true를 더하세요. 구조화된 출력(structured outputs)이 적용되어 Claude의 도구 입력이 스키마와 정확히 일치하도록 보장합니다(타입 불일치·필드 누락 방지). 모델은 복잡하고 모호한 작업일수록 최신 Opus가 다중 도구를 더 잘 다루고 필요 시 되묻습니다. 단순한 도구엔 Haiku도 좋지만, 누락된 파라미터를 추론할 수 있다는 점에 유의합니다.
2. 에이전트 루프와 에러 처리
도구를 쓰는 대화는 반복 루프입니다. API를 호출하고 → stop_reason을 확인하고 → 도구를 실행하고 → 결과를 메시지에 덧붙이는 과정을, stop_reason == "tool_use"인 동안 반복합니다. 루프는 end_turn·max_tokens·stop_sequence·refusal 같은 다른 종료 이유에서 빠져나옵니다.
도구는 실패할 수 있습니다. 캘린더 API가 참석자 초과로 거절하거나 날짜 형식이 잘못될 수 있죠. 이때 충돌시키지 말고 결과 블록에 is_error: true와 에러 메시지를 담아 돌려주세요. Claude는 에러를 읽고 입력을 고쳐 재시도하거나, 사용자에게 되묻거나, 한계를 설명합니다. 성공 결과와의 유일한 차이는 이 플래그뿐입니다.
{
"type": "tool_result",
"tool_use_id": "toolu_02",
"is_error": true,
"content": "cat: report.md: No such file or directory"
}대부분의 SDK에는 이 루프(에러 래핑·결과 포맷·대화 관리)를 자동 처리하는 Tool Runner가 있습니다. 직접 세밀하게 제어할 필요가 없다면 Tool Runner를 쓰는 편이 간단합니다.
3. 병렬 도구 호출 — 결과 포맷 규칙
기본적으로 Claude는 한 턴에 독립적인 여러 도구를 동시에 호출할 수 있습니다. 이때 포맷 규칙을 어기면 병렬 처리가 깨집니다.
- 병렬 호출의 모든 결과는 하나의 user 메시지에 담고, 각 결과는 개별
tool_result블록으로 넣습니다. - user 메시지의 content 배열에서 tool_result 블록이 맨 앞에 와야 하며, 어떤 텍스트든 모든 결과 뒤에 와야 합니다.
tool_result는 대응하는tool_use바로 다음에 와야 하고, 그 사이에 다른 메시지를 끼울 수 없습니다.- 한 턴의 도구 호출은 순서가 없습니다. 동시(예: Promise.all, asyncio.gather)·순차·임의 순서로 실행해도 됩니다.
한 배치 안의 호출이 서로 의존해 실패하면, 의존성을 설명할 필요 없이 그냥 is_error: true와 자연스러운 에러 메시지를 돌려주세요. Claude가 회복해 다시 호출합니다. 병렬을 끄려면 tool_choice가 auto일 때 disable_parallel_tool_use=true로 최대 한 개만, any/tool일 때는 정확히 한 개만 쓰게 할 수 있습니다.
4. 도구가 많아질 때
도구 정의에는 정해진 개수 제한은 없지만, 정의가 많아질수록 컨텍스트를 더 소비합니다. 도구 수가 많은(대략 수십 개 이상) 설정에서는 정의만으로도 상당한 토큰을 쓸 수 있습니다. 이런 경우 공식 문서가 안내하는 Tool Search와 defer_loading 같은 동적 발견 패턴을 적용해, 필요한 도구만 그때그때 불러오도록 설계하는 것이 좋습니다.
함께 보면 좋은 글
도구 사용의 작동 원리는 Tool Use 완벽 가이드, 출력 형식을 JSON 스키마로 강제하는 법은 구조화된 출력에서 다룹니다.
참고: 본 글은 Anthropic 공식 도구 사용 문서(2026년 9월 9일 재대조)를 바탕으로 하며, API 세부·베타 기능·모델 권장 사항은 이후 변동될 수 있습니다. 정확한 최신 사양은 공식 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.