콘텐츠로 이동

도구 정의 (Define Tools)

원문: Define tools · Claude 공식 문서의 한국어 번역

시작 전에

도구(tool)를 제대로 쓰려면 먼저 이 문서의 전제 조건을 갖추고 와야 해요.

참고 — 도구 사용(thinking)과 함께 Claude를 쓴다면 Thinking 문서도 함께 보는 걸 권할게요.

이 문서에서 다룰 내용은 크게 세 가지예요. 도구 스키마를 어떻게 명시하는지, 효과적인 설명을 어떻게 쓰는지, 그리고 Claude가 언제 도구를 호출하도록 통제하는지. 차례로 살펴볼게요.

클라이언트 도구 명시하기 (Specifying client tools)

클라이언트 도구는 API 요청의 tools 최상위(top-level) 파라미터에 명시해요.

bash나 text editor 같은 Anthropic 스키마(Anthropic-schema) 클라이언트 도구는 날짜 버전이 붙은 type으로 선언돼요. 각 도구가 어떤 필드를 받는지는 도구 참조(Tool reference)에서 각 도구 페이지로 연결된 곳을 보면 돼요.

반면 computer use와 browser use 도구는 클라이언트 도구셋(client toolsets)이에요. name이 없는 단일 엔트리로, 고정된 멤버 도구 묶음을 선언하는 방식이죠. 사용자가 정의하는 도구(user-defined tool) 정의에는 다음 항목이 포함돼요.

파라미터 설명
input_examples (선택) 도구를 어떻게 사용하는지 Claude가 이해하도록 돕는 예시 입력 객체의 배열이에요. 자세한 내용은 도구 사용 예시 제공을 참고하세요.

도구 정의 한 개에 쓸 수 있는 선택 속성 전체 — cache_control, strict, defer_loading, allowed_callers까지 — 는 도구 참조(Tool reference)에서 확인할 수 있어요. 클라이언트 도구셋 엔트리는 엔트리 수준에서 cache_control과 allowed_callers를 받고, 멤버별로는 defer_loading을 설정해요. 자세한 내용은 클라이언트 도구셋(Client toolsets)을 보세요.

도구 사용 시스템 프롬프트 (Tool use system prompt)

도구를 사용할 때 시스템 프롬프트는 세 부분으로 구성돼요.

```text wrap {{ TOOL DEFINITIONS IN JSON SCHEMA }} {{ USER SYSTEM PROMPT }} {{ TOOL CONFIGURATION }} 

첫 번째 자리에는 도구 정의가 JSON 스키마 형태로 들어가고, 그다음 사용자 시스템 프롬프트, 마지막에 도구 설정이 이어져요.

### 도구 정의 모범 사례 (Best practices for tool definitions)

도구를 잘 정의하는 것이 도구를 잘 쓰는 지름길이에요. 몇 가지 지켜두면 좋을 규칙을 정리했어요.

각 도구 설명은 **최소 3~4문장**을 목표로 해요. 도구가 복잡하다면 그보다 더 길게 써도 좋아요. 한두 문장으로 퉁치면 Claude가 도구의 역할을 오해하기 쉬워져요.

도구 라이브러리가 커질수록 도구 선택이 애매해지지 않도록 설명을 분명히 쓰는 게 점점 중요해져요. 특히 [도구 검색(tool search)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)을 쓸 때 그렇죠. 이름과 설명이 명확해야 Claude가 어떤 도구를 골라야 할지 헷갈리지 않아요.

설명이 부풀려진(bloated) 응답은 컨텍스트를 낭비하고, Claude가 중요한 것을 뽑아내기도 어렵게 만들어요. 필요한 만큼만, 정확하게 쓰는 게 좋아요.

도구 사용 예시 제공에 대한 더 자세한 내용은 [도구 사용 예시 제공(Providing tool use examples)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) 항목을 보세요.

> **팁** — 도구 설계(통합·consolidation, 명명, 응답 형태)에 대한 더 깊은 안내는 [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)를 참고하세요.

## 도구 사용 예시 제공하기 (Providing tool use examples)

`input_examples`로 도구 사용 예시를 넣으면 Claude가 도구를 더 잘 이해해요. 기본 사용 방식부터 볼게요.

### 기본 사용 (Basic usage)

아래는 `get_weather` 도구를 정의하고, 사용자 메시지로 "샌프란시스코 날씨가 어때?"라고 물어보는 요청이에요.

```bash cURL
curl -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<'EOF'
{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
        {"location": "Tokyo, Japan", "unit": "celsius"},
        {"location": "New York, NY"}
      ]
    }
  ],
  "messages": [
    {"role": "user", "content": "What's the weather like in San Francisco?"}
  ]
}
EOF

같은 요청을 YAML(CLI 문법)로 쓰면 아래처럼 돼요. unit은 선택 항목이라 주석으로 표시해 둔 걸 볼 수 있어요.

```bash CLI - location: Tokyo, Japan unit: celsius - location: New York, NY # 'unit' is optional messages: - role: user content: What's the weather like in San Francisco? 

Ruby SDK로는 아래처럼 작성해요.

```ruby Ruby
    { role: "user", content: "What's the weather like in San Francisco?" }
  ]
)
puts message

Claude의 출력 통제하기 (Controlling Claude's output)

도구 사용을 설계할 때 자주 필요한 것이 있는데, 바로 Claude가 언제 어떤 도구를 쓰도록 강제할지 정하는 일이에요.

도구 사용 강제하기 (Forcing tool use)

tool_choice 파라미터로 도구 사용을 통제할 수 있는데, 몇몇 모델과 설정에서는 제약이 있어요. 아래 표를 확인하세요.

모델 또는 설정 제약 대신 쓸 것
수동 확장 사고(extended thinking) (thinking: {type: "enabled"}) any와 tool을 지원하지 않아 오류가 나요 auto 또는 none
적응형 사고(adaptive thinking) — Claude Opus 5처럼 사고가 기본 켜진 모델 포함 도구 사용 강제를 지원해요
Claude Fable 5.1과 Claude Mythos 5.1 any와 tool이 400 오류를 반환해요 strict tool use와 함께 auto를 써서 스키마에 맞는 도구 입력을 보장하거나, 고정된 JSON 형태의 응답이 필요하면 structured outputs를 써요. 프롬프팅은 여전히 auto가 어떤 도구를 고르는지에 영향을 줘요. none도 지원돼요

tool_choice로 특정 도구 사용을 강제하는 요청은 아래처럼 작성해요.

```bash cURL curl -sS https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d @- <<'EOF' { "model": "claude-opus-5", "max_tokens": 1024, "tools": [ { "name": "get_weather", 

YAML(CLI)로는 `tool_choice`를 아래처럼 명시해요.

```bash CLI
          description: The city and state, e.g. San Francisco, CA
      required: [location]
tool_choice:
  type: tool
  name: get_weather
messages:
  - role: user
    content: What's the weather like in San Francisco?

Go SDK로는 아래처럼 쓰고 응답을 확인해요.

```go Go if err != nil { log.Fatal(err) } fmt.Println(response.RawJSON()) 

PHP SDK로는 아래 처럼요.

```php PHP
$client = new Client();

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
    ],
    model: 'claude-opus-5',
    toolChoice: ['type' => 'tool', 'name' => 'get_weather'],
    tools: [
        [
            'name' => 'get_weather',
            'description' => 'Get the current weather in a given location',
            'input_schema' => [
                'type' => 'object',
                'properties' => [
                    'location' => [
                        'type' => 'string',

tool_choice 파라미터를 다룰 때는 네 가지 옵션이 있어요.

  • auto — Claude가 제공된 도구 중 어느 것을 호출할지 스스로 정하게 해요. tools가 제공됐을 때의 기본값이에요.
  • any — 제공된 도구 중 하나를 반드시 사용하게 해요. 특정 도구를 강제하지는 않아요.
  • tool — Claude가 항상 특정 도구 하나를 사용하게 강제해요.
  • none — Claude가 어떤 도구도 사용하지 못하게 해요. tools가 제공되지 않았을 때의 기본값이에요.

참고 — 프롬프트 캐싱(prompt caching)을 쓸 때 tool_choice 파라미터가 바뀌면 캐시된 메시지 블록이 무효화돼요. 도구 정의와 시스템 프롬프트는 캐시에 남지만, 메시지 내용은 다시 처리해야 해요.

아래 다이어그램이 각 옵션이 어떻게 동작하는지 보여줘요.

네 가지 tool_choice 옵션(auto, any, tool, none)을 보여주는 다이어그램

한 가지 주의할 점이 있어요. tool_choice를 any나 tool로 두면, API가 어시스턴트 메시지를 미리 채워(prefill) 도구를 쓰도록 강제해요. 그래서 이 경우 모델은 tool_use 콘텐츠 블록 앞에 자연어 응답이나 설명을 만들지 않아요. 명시적으로 그렇게 요청해도 마찬가지예요.

간접적으로 도구를 쓰도록 유도하려면 프롬프트에서 힌트를 주면 돼요. 예를 들어 What's the weather like in London? Use the get_weather tool in your response.처럼 말이죠.

도구 사용 강제를 지원하는 모델에서는 tool_choice: {"type": "any"}를 strict tool use와 함께 쓰면 도구가 하나는 반드시 호출되면서, 입력이 스키마를 엄격히 따르는 것까지 보장할 수 있어요.

도구와 함께하는 모델 응답 (Model responses with tools)

도구를 사용할 때 Claude는 도구를 호출하기 전에 자주 자기 행동을 언급하거나 사용자에게 자연스럽게 응답해요.

예를 들어 "지금 샌프란시스코 날씨가 어때? 거기 지금 몇 시야?"라는 프롬프트에 Claude는 아래처럼 응답할 수 있어요.

json JSON { "role": "assistant", "content": [ { "type": "text", "text": "I'll help you check the current weather and time in San Francisco." }, { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": { "location": "San Francisco, CA" } } ] }

이런 자연스러운 응답 스타일은 사용자가 Claude가 무엇을 하고 있는지 이해하게 도와주고, 더 대화적인 상호작용을 만들어요. 이런 응답의 스타일과 내용은 시스템 프롬프트와 프롬프트 안의 <examples>를 통해 조절할 수 있어요.

다음 단계 (Next steps)