도구 사용 개요 (Tool Use Overview)¶

도구 사용(Tool use)은 함수 호출(function calling)이라고도 부르는데요, Claude가 여러분이 정의한 함수나 Anthropic이 제공하는 함수를 호출할 수 있게 해주는 기능이에요. Claude는 사용자의 요청과 도구의 설명을 바탕으로 언제 도구를 호출할지 스스로 결정해요. 그러면 구조화된 호출을 돌려주는데, 여러분의 애플리케이션이 그 호출을 실행하기도(client tools) 하고, Anthropic이 직접 실행하기도 해요(server tools).

가장 간단한 예를 하나 볼게요. 서버 도구인 Web search tool로, 검색은 Anthropic이 대신 실행해 주는 도구예요:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude는 Anthropic의 인프라에서 검색을 실행하고, 출처가 표시된 결과를 같은 응답에 담아 돌려줘요. 여러분이 직접 정의한 함수를 Claude가 호출하게 하려면 input_schema가 있는 도구를 넘겨주면 되고, Claude가 tool_use 블록을 돌려줬을 때 그 호출을 실행하면 돼요. How tool use works에서 그 왕복(round trip) 과정을 처음부터 끝까지 보여드릴게요. 도구 정의와 도구 호출 처리도 함께 살펴보면 좋아요.

도구 사용이 동작하는 방식¶

도구들의 차이는 기본적으로 코드가 어디서 실행되느냐에서 나와요. 클라이언트 도구(사용자가 정의한 도구와, bash·text_editor처럼 Anthropic이 스키마를 만든 도구를 포함해요)는 여러분의 애플리케이션에서 실행돼요. 그러면 Claude는 stop_reason: "tool_use"와 함께 하나 이상의 tool_use 블록으로 응답하고, 여러분의 코드가 그 연산을 실행한 뒤 tool_result로 결과를 보내줘요. 서버 도구(web_search, web_fetch, code_execution, tool_search 같은 것들)는 Anthropic의 인프라에서 실행되므로, 여러분이 실행 처리를 직접 다룰 필요 없이 결과를 바로 볼 수 있어요. 다만 Claude가 병렬 도구 호출 그룹 안에서 여러분의 클라이언트 도구와 함께 이들을 호출하는 경우는 예외예요 (Stop reasons and fallback 참고).

클라이언트 도구의 왕복 과정을 전체로 보여드릴게요. 첫 번째 요청에서 get_weather 도구를 정의하고, Claude는 그 도구를 호출하면서 질문에 답해요. 응답에 tool_use 블록이 실려 오고, 여러분의 코드가 조회를 실행한 뒤, 두 번째 요청에서 tool_result 블록으로 결과를 다시 보내면 Claude가 최종 답변을 하게 돼요.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude replies with a tool_use block naming the tool and its arguments.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # Ask for at most one tool call per turn.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Run the tool, then send the result back in a tool_result block.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude uses the result to answer the original question.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

출력(Output):

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

도구 호출 처리 문서에서 각 단계가 자세히 설명돼 있어요. 결과 형식과 오류 전달 방식까지 다루니까요. 병렬 도구 사용은 한 번에 여러 도구를 호출하는 응답을 다루고요. 이 왕복 과정을 직접 작성하지 않으려면 Tool Runner를 쓰면 돼요. SDK가 여러분의 도구를 실행하고 결과를 자동으로 다시 보내주거든요.

에이전트 루프(agentic loop)를 포함한 전체 개념 모델과 각 접근 방식을 언제 선택할지는 How tool use works에서 확인할 수 있어요.

Model Context Protocol(MCP) 서버에 연결하려면 MCP connector를 보면 되고요, 직접 MCP 클라이언트를 만들려면 Model Context Protocol 가이드의 MCP 클라이언트 구축 문서를 참고하세요.

Claude가 도구를 사용하는 시점¶

기본 tool_choice가 {"type": "auto"}일 때, Claude는 매 턴마다 도구를 호출할지 직접 답할지를 스스로 정해요. 요청이 그 도구에 설명된 기능과 맞아떨어지고, 답이 이미 맥락에 없다면 도구를 호출해요. 반대로 안정적인 지식이나 창의적인 작업, 대화적인 턴에는 직접 응답하고요.

이 경계는 시스템 프롬프트를 통해 조절할 수 있어요. 기대한 만큼 도구를 호출하지 않을 때는 "Use the tools to investigate before responding." 같은 가벼운 지시만으로도 도구 사용이 늘어나요. "Always call a tool first before responding."처럼 더 강한 표현을 쓰면 더 밀어붙일 수 있고요. 반대로 "Use your judgment about whether to call a tool or respond directly."는 트리거 동작을 보수적으로 유지해 줘요.

프롬프트에 의존하지 않고 도구 호출을 강제하려면 tool_choice를 설정하면 돼요.

각 서버 도구의 페이지에서 각자의 트리거 경계를 더 자세히 설명하고 있어요.

필수 파라미터가 빠져 있을 때¶

사용자의 프롬프트가 도구의 모든 필수 파라미터를 채울 만큼의 정보를 담고 있지 않다면, Claude Opus는 파라미터가 빠졌다는 걸 인지하고 되묻는 경우가 훨씬 많아요. Claude Sonnet도 물어보긴 하는데, 특히 도구 요청을 내보내기 전에 생각하라는 프롬프트가 있을 때요. 다만 합리적인 값을 스스로 추론할 수도 있어요.

예를 들어 location 파라미터가 필수인 get_weather 도구를 쓸 때, 위치를 지정하지 않고 "What's the weather?"라고 물으면 Claude(Sonnet이 특히 그러해요)가 여러분이 주지 않은 값을 추측할 수 있어요:

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

이 동작은 보장되지 않아요. 특히 더 모호한 프롬프트나 성능이 낮은 모델에서는요.

도구 선택하기¶

type 문자열, 버전, 베타 헤더에 대해서는 도구 레퍼런스를 참고하세요.

직접 정의한 도구¶

직접 정의한 도구는 여러분이 스키마를 작성하고, 여러분의 애플리케이션이 각 호출을 실행해요.

도구 정의 — 도구 스키마 지정, 설명 작성, Claude가 도구를 호출하는 시점 제어

도구 호출 처리 — tool_use 블록 파싱, tool_result 응답 형식화, 오류 처리

Anthropic 스키마 클라이언트 도구¶

Anthropic이 스키마를 공개하고 그에 맞춰 Claude를 훈련시켜요. 여러분의 애플리케이션은 여전히 각 호출을 실행하고 tool_result를 돌려줘요.

Memory tool — 대화 간 정보를 여러분이 제어하는 파일에 저장하고 가져오기

Bash tool — 상태를 유지하는 지속 세션에서 셸 명령 실행

Text editor tool — 텍스트 파일을 보고 수정해 디버깅·수정·개선

Computer use tool — 데스크톱 환경에서 스크린샷을 찍고 마우스·키보드 제어

Browser use tool — 여러분의 브라우저 환경에서 웹페이지 탐색, 읽기, 상호작용

서버 도구¶

서버 도구는 여러분의 애플리케이션에 핸들러 코드 없이 Anthropic의 인프라에서 실행돼요. 공통 메커니즘은 서버 도구 문서에서 확인할 수 있어요.

Web search tool — 지식 컷오프 이후의 정보를 출처와 함께 웹에서 검색

Web fetch tool — 지정한 웹 페이지와 PDF 문서의 전체 내용 가져오기

Code execution tool — 샌드박스 컨테이너에서 Python·bash 코드를 실행해 데이터 분석·파일 생성

Advisor tool — 더 빠른 실행 모델이 생성 중에 고지능 어드바이저 모델과 상의

Tool search tool — 도구를 요청 시 로드해 수천 개의 도구와 작업

MCP connector — 별도 MCP 클라이언트 없이 Messages API에서 원격 MCP 서버에 연결

가격 (Pricing)¶

도구 사용 요청은 다음을 기준으로 과금돼요:

모델에 보내진 입력 토큰의 총합(tools 파라미터에 실린 것까지 포함)
생성된 출력 토큰 수
서버 측 도구의 경우 추가 사용량 기반 과금(예를 들어 웹 검색은 검색 1회당 과금)

클라이언트 측 도구는 다른 Claude API 요청과 동일하게 과금되지만, 서버 측 도구는 각자의 특정 사용량에 따라 추가 비용이 발생할 수 있어요.

도구 사용에서 추가로 들어오는 토큰은 여기서 나와요:

API 요청의 tools 파라미터(도구 이름, 설명, 스키마)
API 요청·응답의 tool_use 콘텐츠 블록
API 요청의 tool_result 콘텐츠 블록

tools를 사용하면 API가 도구 사용을 가능하게 하는 특수 시스템 프롬프트를 모델에 자동으로 포함해요. 각 모델에 필요한 도구 사용 토큰 수는 아래 표에 정리돼 있는데, 앞서 언급한 추가 토큰은 제외한 값이에요. 이 표는 최소 1개의 도구가 제공된다고 가정해요. tools가 없으면 none 도구 선택은 시스템 프롬프트 토큰을 0개 추가로 사용해요.

모델	도구 선택	도구 사용 시스템 프롬프트 토큰 수
Claude Opus 5	`auto`, `none` * * * `any`, `tool`	286 tokens * * * 406 tokens
Claude Opus 4.8	`auto`, `none` * * * `any`, `tool`	290 tokens * * * 410 tokens
Claude Opus 4.7	`auto`, `none` * * * `any`, `tool`	675 tokens * * * 804 tokens
Claude Opus 4.6	`auto`, `none` * * * `any`, `tool`	497 tokens * * * 589 tokens
Claude Opus 4.5	`auto`, `none` * * * `any`, `tool`	496 tokens * * * 588 tokens
Claude Opus 4.1 (retired, except on Bedrock and Google Cloud)	`auto`, `none` * * * `any`, `tool`	313 tokens * * * 315 tokens
Claude Opus 4 (retired, except on Google Cloud)	`auto`, `none` * * * `any`, `tool`	313 tokens * * * 315 tokens
Claude Sonnet 5	`auto`, `none` * * * `any`, `tool`	354 tokens * * * 474 tokens
Claude Sonnet 4.6	`auto`, `none` * * * `any`, `tool`	497 tokens * * * 589 tokens
Claude Sonnet 4.5	`auto`, `none` * * * `any`, `tool`	496 tokens * * * 588 tokens
Claude Sonnet 4 (retired, except on Bedrock and Google Cloud)	`auto`, `none` * * * `any`, `tool`	313 tokens * * * 315 tokens
Claude Haiku 4.5	`auto`, `none` * * * `any`, `tool`	496 tokens * * * 588 tokens
Claude Haiku 3.5 (retired, except on Bedrock and Google Cloud)	`auto`, `none` * * * `any`, `tool`	264 tokens * * * 355 tokens

이 토큰 수는 일반 입력·출력 토큰에 더해져 요청의 총비용을 계산해요.

각 모델의 최신 가격은 모델 개요 표에서 확인할 수 있어요.

도구 사용 프롬프트를 보내면 다른 API 요청처럼 응답에도 입력·출력 토큰 수가 usage 메트릭으로 함께 보고돼요.

일부 서버 도구는 토큰 위에 사용량 기반 요금을 추가해요. 요율은 Web search tool과 Code execution tool 문서에서 확인할 수 있어요.

다음 단계 (Next steps)¶

How tool use works — 도구 사용 루프, 도구가 실행되는 위치, 일반 문장 대신 도구를 써야 할 때를 이해

튜토리얼: 도구를 쓰는 에이전트 구축 — 단일 도구 호출에서 운영 준비가 된 에이전트 루프까지 단계별 안내

도구 레퍼런스 — Anthropic 제공 도구 디렉터리와 선택적 도구 정의 속성 레퍼런스