도구 사용(Tool Use, 함수 호출이라고도 함)은 Claude가 직접 할 수 없는 일 — 외부 데이터 조회, 파일 쓰기, 계산 등 — 을 위해 개발자가 정의한 함수나 Anthropic이 제공하는 도구를 호출하게 하는 기능입니다. 이 글은 도구 사용의 작동 원리를 입문자 관점에서 정리합니다. (기준 시점: 2026년 6월. 세부 내용·도구 목록은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)
도구 사용이란 무엇인가 — "계약"으로 이해하기
도구 사용은 내 애플리케이션과 모델 사이의 계약(contract)입니다. 내가 "어떤 작업이 가능한지"와 "입력·출력의 형태"를 정의하면, Claude는 언제·어떻게 그 작업을 호출할지 결정합니다. 중요한 점은 모델이 스스로 코드를 실행하지 않는다는 것입니다. 모델은 구조화된 호출 요청만 내보내고, 실제 실행은 내 코드(또는 Anthropic 서버)가 담당하며, 그 결과가 다시 대화로 돌아옵니다.
덕분에 모델은 단순한 텍스트 생성기보다 "내가 호출하는 함수"처럼 동작합니다. 스키마를 정의하고, 콜백을 처리하고, 결과를 반환하는 일반적인 API 통합과 같은 방식으로 다룰 수 있습니다. 차이가 있다면 호출하는 쪽이 사람이 아니라, 대화 맥락을 보고 어떤 함수를 부를지 고르는 언어 모델이라는 점입니다.
도구가 실행되는 세 가지 위치
도구를 나누는 가장 핵심 기준은 코드가 어디서 실행되는가입니다. 모든 도구는 아래 세 가지 중 하나에 속하며, 분류에 따라 내 앱이 책임지는 범위가 달라집니다.
- ① 사용자 정의 도구(클라이언트 실행): 스키마도 내가 작성하고, 코드도 내가 실행하고, 결과도 내가 반환합니다. 도구 사용 트래픽의 대부분이 여기에 해당하며, 보통 애플리케이션 고유 로직(DB 조회, 외부 API 호출, 파일 쓰기 등)을 부릅니다.
- ② Anthropic 스키마 도구(클라이언트 실행): 셸 명령 실행, 파일 편집, 브라우저 제어, 메모리 관리처럼 흔한 작업은 Anthropic이 도구 스키마를 미리 정의해 두었고, 실행은 내 앱이 맡습니다. 해당 도구는
bash,text_editor,computer,memory입니다. 동작 방식은 사용자 정의 도구와 동일하지만, 이 스키마들은 모델 학습에 반영돼 있어 직접 만든 동등한 도구보다 더 안정적으로 호출되는 경향이 있습니다. - ③ 서버 실행 도구:
web_search,web_fetch,code_execution,tool_search는 Anthropic이 직접 실행합니다. 요청에서 도구를 활성화만 하면 서버가 나머지를 처리하므로, 이 도구들에 대해서는 내가tool_result블록을 구성할 필요가 없습니다.
에이전트 루프: 단계별 흐름 (클라이언트 도구)
클라이언트가 실행하는 도구(① 사용자 정의 + ② Anthropic 스키마)는 내 앱이 루프를 돌려야 합니다. 모델이 내 코드를 실행할 수 없으므로, 모든 도구 호출은 "모델이 요청 → 내가 실행 → 결과 보고 → 모델이 이어감"의 왕복이 됩니다.
tools배열과 사용자 메시지를 담아 요청을 보냅니다.- Claude가
stop_reason: "tool_use"와 함께 하나 이상의tool_use블록으로 응답합니다. - 각 도구를 실행하고, 출력을
tool_result블록으로 포맷합니다. - 원래 메시지 + 모델 응답 +
tool_result를 담은 새 요청을 보냅니다. stop_reason이"tool_use"인 동안 2번부터 반복합니다.
루프는 stop_reason이 그 외의 값(end_turn, max_tokens, stop_sequence, refusal)이 되면 종료됩니다. 즉 Claude가 최종 답을 냈거나, 앱이 처리해야 할 다른 이유로 멈춘 것입니다.
도구는 어떻게 정의하나
클라이언트 도구(사용자 정의·Anthropic 정의 모두)는 API 요청의 최상위 tools 파라미터에 넣습니다. 각 도구 정의에는 보통 다음이 들어갑니다: 이름(name), 설명(description), 입력 스키마(input_schema, JSON Schema 형식). 설명을 구체적으로 적을수록 모델이 도구를 더 정확히 호출합니다.
{
"name": "get_weather",
"description": "지정한 도시의 현재 날씨를 조회한다",
"input_schema": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "도시 이름" }
},
"required": ["city"]
}
}모델이 이 도구를 쓰기로 하면 응답에 tool_use 블록(도구 이름 + 인자 JSON)이 담깁니다. 내 앱은 인자를 꺼내 작업을 실행한 뒤, 다음 요청에 tool_result 블록으로 출력을 돌려줍니다. Claude는 내 구현 코드를 보지 못하며, 내가 제공한 스키마와 내가 돌려준 결과만 봅니다.
// Claude가 반환하는 tool_use 블록(예시)
{
"type": "tool_use",
"id": "toolu_01A...",
"name": "get_weather",
"input": { "city": "Seoul" }
}
// 앱이 실행 후 다음 요청에 담아 보내는 tool_result 블록
{
"type": "tool_result",
"tool_use_id": "toolu_01A...",
"content": "맑음, 22도"
}위 코드는 형식 이해를 돕기 위한 예시입니다(실제 필드·식별자 형식은 공식 문서를 따르세요). 도구를 정의할 때 API는 도구 사용을 활성화하는 특수 시스템 프롬프트를 자동으로 추가하며, 그만큼 추가 토큰이 비용에 포함됩니다.
언제 도구를 쓰고, 언제 쓰지 않나
도구 사용은 모델이 텍스트만으로 할 수 없는 일이 필요할 때 적합합니다.
- 부수효과가 있는 행동: 이메일 전송, 파일 쓰기, 레코드 업데이트 등. 모델은 이런 행동을 "설명"할 수는 있어도, 실제 수행은 도구만 할 수 있습니다.
- 최신·외부 데이터: 현재 가격, 오늘 날씨, 데이터베이스 내용처럼 학습 데이터 밖이거나 내 시스템에 특화된 정보는 도구로 가져와야 합니다.
- 형태가 보장된 구조화 출력: 자유 서술이 아니라 특정 필드를 가진 JSON이 필요할 때.
반대로 모델이 이미 가진 지식이나 추론만으로 충분한 작업이라면, 도구 없이 일반 텍스트 응답이 더 단순하고 빠릅니다.
서버 도구와 일시중지(pause_turn)
서버 실행 도구는 Anthropic 인프라 안에서 자체 루프를 돕니다. 내 앱의 요청 하나가 여러 번의 웹 검색이나 코드 실행을 유발할 수 있으며, 모델은 검색하고 결과를 읽고 다시 검색하기를 반복합니다 — 이 과정에 내 앱은 참여하지 않습니다.
이 내부 루프에는 반복 한도가 있습니다. 모델이 한도에 도달했는데도 아직 작업 중이면, 응답이 end_turn 대신 stop_reason: "pause_turn"으로 돌아옵니다. 일시중지된 턴은 작업이 끝나지 않았다는 뜻이므로, 일시중지된 응답을 포함해 대화를 다시 보내면 모델이 멈춘 지점부터 이어갑니다.
정리
도구 사용은 "모델이 결정하고, 코드는 실행한다"는 계약입니다. 핵심만 기억하세요: ① 모델은 호출만 요청할 뿐 직접 실행하지 않는다, ② 도구는 실행 위치에 따라 사용자 정의·Anthropic 스키마·서버 실행으로 나뉜다, ③ 클라이언트 도구는 tool_use → 실행 → tool_result의 루프를 내 앱이 돌려야 한다. 더 깊은 구현(도구 정의, 호출 처리, 병렬 호출 등)은 Claude 공식 도구 사용 문서를 참고하세요.
이 글은 Anthropic 공식 문서를 토대로 작성한 입문 설명입니다. API 동작·필드·도구 목록은 업데이트될 수 있으므로, 실제 구현 전 반드시 공식 문서에서 최신 사양을 확인하세요. (공식 출처: docs.claude.com)