도구 정의



사전 요구 사항

• 도구 사용 개요에 대한 이해
• Claude API 키와 작동하는 SDK 또는 cURL 설정



모델 선택

복잡한 도구와 모호한 쿼리에는 최신 Claude Opus 모델인 Claude Opus 5를 사용하세요. 여러 도구를 더 잘 처리하고 필요할 때 명확한 설명을 요청합니다.

간단한 도구에는 Claude Haiku 모델을 사용하되, 누락된 매개변수를 추론할 수 있다는 점에 유의하세요.



클라이언트 도구 지정

클라이언트 도구(Anthropic 스키마 및 사용자 정의 모두)는 API 요청의 tools 최상위 매개변수에 지정됩니다. 각 도구 정의에는 다음이 포함됩니다:

cache_control, strict, defer_loading, allowed_callers를 포함하여 모든 도구 정의에서 사용할 수 있는 선택적 속성의 전체 목록은 도구 참조를 참조하세요.



도구 사용 시스템 프롬프트

tools 매개변수와 함께 Claude API를 호출하면, API는 도구 정의, 도구 구성 및 사용자가 지정한 시스템 프롬프트로부터 특별한 시스템 프롬프트를 구성합니다. 구성된 프롬프트는 모델이 지정된 도구를 사용하도록 지시하고 도구가 올바르게 작동하는 데 필요한 컨텍스트를 제공하도록 설계되었습니다:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}



도구 정의 모범 사례

도구를 사용할 때 Claude에서 최상의 성능을 얻으려면 다음 지침을 따르세요:

• 매우 상세한 설명을 제공하세요. 이것은 도구 성능에서 단연코 가장 중요한 요소입니다. 설명은 다음을 포함하여 도구에 대한 모든 세부 사항을 설명해야 합니다:
  • 도구가 하는 일
  • 언제 사용해야 하는지(그리고 언제 사용하지 말아야 하는지)
  • 각 매개변수가 무엇을 의미하고 도구의 동작에 어떤 영향을 미치는지
  • 도구 이름이 불분명한 경우 도구가 반환하지 않는 정보와 같은 중요한 주의 사항이나 제한 사항. 도구에 대해 Claude에게 더 많은 컨텍스트를 제공할수록 Claude가 언제 어떻게 도구를 사용할지 더 잘 결정할 수 있습니다. 각 도구 설명에 대해 최소 3~4문장을 목표로 하고, 도구가 복잡한 경우 더 많이 작성하세요.
• 설명을 우선시하되, 복잡한 도구에는 input_examples 사용을 고려하세요. 명확한 설명이 가장 중요하지만, 복잡한 입력, 중첩된 객체 또는 형식에 민감한 매개변수가 있는 도구의 경우 input_examples 필드를 사용하여 스키마 검증된 예시를 제공할 수 있습니다. 자세한 내용은 도구 사용 예시 제공을 참조하세요.
• 관련 작업을 더 적은 수의 도구로 통합하세요. 모든 작업에 대해 별도의 도구(create_pr, review_pr, merge_pr)를 만드는 대신, action 매개변수가 있는 단일 도구로 그룹화하세요. 더 적고 더 유능한 도구는 선택의 모호성을 줄이고 Claude가 도구 표면을 더 쉽게 탐색할 수 있게 합니다.
• 도구 이름에 의미 있는 네임스페이스를 사용하세요. 도구가 여러 서비스나 리소스에 걸쳐 있는 경우, 이름 앞에 서비스를 붙이세요(예: github_list_prs, slack_send_message). 이렇게 하면 라이브러리가 커져도 도구 선택이 명확해지며, 도구 검색을 사용할 때 특히 중요합니다.
• 높은 신호 정보만 반환하도록 도구 응답을 설계하세요. 불투명한 내부 참조 대신 의미론적이고 안정적인 식별자(예: 슬러그 또는 UUID)를 반환하고, Claude가 다음 단계를 추론하는 데 필요한 필드만 포함하세요. 비대한 응답은 컨텍스트를 낭비하고 Claude가 중요한 것을 추출하기 어렵게 만듭니다.

좋은 설명은 도구가 무엇을 하는지, 언제 사용하는지, 어떤 데이터를 반환하는지, ticker 매개변수가 무엇을 의미하는지 명확하게 설명합니다. 나쁜 설명은 너무 간략하여 Claude가 도구의 동작과 사용법에 대해 많은 의문을 갖게 합니다.



도구 사용 예시 제공

Claude가 도구를 더 효과적으로 사용하는 방법을 이해하도록 유효한 도구 입력의 구체적인 예시를 제공할 수 있습니다. 이는 중첩된 객체, 선택적 매개변수 또는 형식에 민감한 입력이 있는 복잡한 도구에 특히 유용합니다.



기본 사용법

도구 정의에 예시 입력 객체의 배열과 함께 선택적 input_examples 필드를 추가하세요. 각 예시는 도구의 input_schema에 따라 유효해야 합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

예시는 도구 스키마와 함께 프롬프트에 포함되어 Claude에게 올바른 형식의 도구 호출에 대한 구체적인 패턴을 보여줍니다. 이는 Claude가 선택적 매개변수를 포함할 시점, 사용할 형식, 복잡한 입력을 구조화하는 방법을 이해하는 데 도움이 됩니다.



요구 사항 및 제한 사항

• 스키마 검증 - 각 예시는 도구의 input_schema에 따라 유효해야 합니다. 유효하지 않은 예시는 400 오류를 반환합니다
• 서버 측 도구에서는 지원되지 않음 - 입력 예시는 사용자 정의 및 Anthropic 스키마 클라이언트 도구에서 작동하지만, 웹 검색이나 코드 실행과 같은 서버 도구에서는 작동하지 않습니다
• 토큰 비용 - 예시는 프롬프트 토큰에 추가됩니다: 간단한 예시의 경우 약 2050 토큰, 복잡한 중첩 객체의 경우 약 100200 토큰



Claude의 출력 제어



도구 사용 강제

경우에 따라 Claude가 도구를 호출하지 않고 직접 답변할 수 있는 경우에도 사용자의 질문에 답하기 위해 특정 도구를 사용하도록 하고 싶을 수 있습니다. 요청의 tool_choice 필드에 도구를 지정하여 이를 수행할 수 있습니다. 강조 표시된 줄이 표준 도구 사용 요청과의 유일한 차이점입니다:

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

tool_choice 매개변수를 사용할 때 네 가지 옵션이 있습니다:

• auto는 Claude가 제공된 도구를 호출할지 여부를 결정할 수 있도록 합니다. tools가 제공될 때의 기본값입니다.
• any는 Claude가 제공된 도구 중 하나를 반드시 사용해야 하지만 특정 도구를 강제하지는 않습니다.
• tool은 Claude가 항상 특정 도구를 사용하도록 강제합니다.
• none은 Claude가 도구를 사용하지 못하도록 합니다. tools가 제공되지 않을 때의 기본값입니다.

이 다이어그램은 각 옵션이 작동하는 방식을 보여줍니다:

tool_choice를 any 또는 tool로 설정하면 API가 도구 사용을 강제하기 위해 어시스턴트 메시지를 미리 채운다는 점에 유의하세요. 이는 명시적으로 요청하더라도 모델이 tool_use 콘텐츠 블록 전에 자연어 응답이나 설명을 출력하지 않는다는 것을 의미합니다.

테스트 결과 이것이 성능을 저하시키지 않는 것으로 나타났습니다. 모델이 특정 도구를 사용하도록 요청하면서도 자연어 컨텍스트나 설명을 제공하도록 하려면, tool_choice에 {"type": "auto"}(기본값)를 사용하고 user 메시지에 명시적인 지침을 추가할 수 있습니다. 예: What's the weather like in London? Use the get_weather tool in your response.



도구를 사용한 모델 응답

도구를 사용할 때 Claude는 도구를 호출하기 전에 자신이 하고 있는 일에 대해 언급하거나 사용자에게 자연스럽게 응답하는 경우가 많습니다.

예를 들어, "What's the weather like in San Francisco right now, and what time is it there?"라는 프롬프트가 주어지면 Claude는 다음과 같이 응답할 수 있습니다:

{
  "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>를 제공하여 이러한 응답의 스타일과 내용을 안내할 수 있습니다.

Claude가 자신의 행동을 설명할 때 다양한 표현과 접근 방식을 사용할 수 있다는 점에 유의하는 것이 중요합니다. 코드는 이러한 응답을 다른 어시스턴트 생성 텍스트와 동일하게 처리해야 하며, 특정 형식 규칙에 의존해서는 안 됩니다.



다음 단계