Claude 개발자 플랫폼에서의 고급 도구 사용 소개

https://www.anthropic.com/engineering/advanced-tool-use

우리는 Claude가 도구를 동적으로 발견하고, 학습하고, 실행할 수 있게 하는 새로운 베타 기능 세 가지를 추가했습니다. 작동 방식은 다음과 같습니다.

AI 에이전트의 미래는 모델이 수백, 수천 개의 도구를 매끄럽게 활용하는 것입니다. Git 운영, 파일 조작, 패키지 관리자, 테스트 프레임워크, 배포 파이프라인을 통합한 IDE 어시스턴트. Slack, GitHub, Google Drive, Jira, 회사 데이터베이스, 수십 개의 MCP 서버를 동시에 연결하는 운영 코디네이터.

효율적인 에이전트 구축을 위해서는, 모든 정의를 미리 컨텍스트에 채워 넣지 않고도 무제한 도구 라이브러리와 함께 작동해야 합니다. MCP를 활용한 코드 실행에 관한 블로그 글에서, 도구 결과와 정의가 때로는 에이전트가 요청을 읽기 전에 50,000+ 토큰을 소모한다고 논의했습니다. 에이전트는 작업에 맞춰 온디맨드로 도구를 발견하고 로드하며, 현재 작업에 관련된 것만 유지해야 합니다.

또한 에이전트는 코드에서 도구를 호출할 수 있어야 합니다. 자연어 도구 호출을 사용할 때는 각 호출에 전체 추론 패스가 필요하고, 중간 결과는 유용한지 여부와 관계없이 컨텍스트에 쌓입니다. 루프, 분기, 데이터 변환 같은 오케스트레이션 로직에는 코드가 자연스럽게 맞습니다. 에이전트는 작업에 따라 코드 실행과 추론 중에서 유연하게 선택할 수 있어야 합니다.

에이전트는 또한 스키마 정의만이 아니라, 예시로부터 올바른 도구 사용법을 학습해야 합니다. JSON 스키마는 구조적으로 유효한 것들을 정의하지만, 언제 선택적 매개변수를 포함할지, 어떤 조합이 의미가 있는지, API가 어떤 관례를 기대하는지 같은 사용 패턴을 표현할 수는 없습니다.

오늘, 이를 가능하게 하는 세 가지 기능을 공개합니다:

• Tool Search Tool: Claude가 컨텍스트 윈도우를 소모하지 않고 수천 개의 도구에 접근할 수 있도록 검색 도구를 사용합니다
• Programmatic Tool Calling: Claude가 코드 실행 환경에서 도구를 호출할 수 있게 하여 모델의 컨텍스트 윈도우에 미치는 영향을 줄입니다
• Tool Use Examples: 특정 도구를 효과적으로 사용하는 방법을 보여주는 범용 표준을 제공합니다

내부 테스트에서, 이러한 기능들은 기존 도구 사용 방식으로는 불가능했던 것들을 구축하도록 도와주었습니다. 예를 들어, Claude for Excel은 Programmatic Tool Calling을 사용하여 수천 행의 스프레드시트를 모델의 컨텍스트 윈도우를 과부하하지 않고 읽고 수정합니다.

우리의 경험에 기반하여, 우리는 이러한 기능들이 Claude로 무엇을 구축할 수 있는지에 대한 새로운 가능성을 연다고 믿습니다.

Claude Opus 4.5 solves a puzzle game

Tool Search Tool

문제

MCP 도구 정의는 중요한 컨텍스트를 제공하지만, 더 많은 서버가 연결될수록 토큰이 누적됩니다. 5개 서버 설정을 고려해보면:

• GitHub: 35개 도구 (~26K 토큰)
• Slack: 11개 도구 (~21K 토큰)
• Sentry: 5개 도구 (~3K 토큰)
• Grafana: 5개 도구 (~3K 토큰)
• Splunk: 2개 도구 (~2K 토큰)

대화가 시작되기도 전에 58개 도구가 약 55K 토큰을 소비합니다. Jira처럼 더 많은 서버를 추가하면(단일로 ~17K 토큰) 금방 100K+ 토큰 오버헤드에 접근합니다. Anthropic에서는 최적화 전 도구 정의가 134K 토큰을 소비하는 것을 목격했습니다.

하지만 토큰 비용만이 문제는 아닙니다. 가장 흔한 실패는 도구 선택 오류와 잘못된 매개변수입니다. 특히 ⁠notification-send-user⁠ vs. ⁠notification-send-channel⁠처럼 이름이 비슷한 도구가 있을 때 그렇습니다.

우리의 해결책

모든 도구 정의를 미리 로드하는 대신, Tool Search Tool은 온디맨드로 도구를 발견합니다. Claude는 현재 작업에 실제로 필요한 도구만 보게 됩니다.

Tool Search Tool은 Claude의 기존 접근과 비교하여 122,800 대비 191,300 토큰의 컨텍스트를 보존합니다.

기존 접근:

• 모든 도구 정의를 미리 로드(50+ MCP 도구에 ~72K 토큰)
• 대화 기록과 시스템 프롬프트가 남은 공간을 두고 경쟁
• 실제 작업 시작 전 전체 컨텍스트 소비: ~77K 토큰

Tool Search Tool 사용 시:

• 초기 로드에는 Tool Search Tool만 포함(~500 토큰)
• 필요한 도구를 온디맨드로 발견(3–5개의 관련 도구, ~3K 토큰)
• 전체 컨텍스트 소비: ~8.7K 토큰, 컨텍스트 윈도우의 95% 보존

이는 풀 도구 라이브러리에 접근하면서도 토큰 사용을 85% 절감함을 의미합니다. 내부 테스트에서는 대규모 도구 라이브러리 작업 시 MCP 평가에서 정확도가 크게 향상되었습니다. Tool Search Tool 활성화로 Opus 4는 49%에서 74%로, Opus 4.5는 79.5%에서 88.1%로 개선되었습니다.

Tool Search Tool 작동 방식

Tool Search Tool은 모든 정의를 미리 로드하는 대신 Claude가 동적으로 도구를 발견할 수 있게 합니다. 모든 도구 정의를 API에 제공하되, ⁠defer_loading: true⁠로 표시하여 온디맨드로 검색 가능하게 만듭니다. 지연 로드된 도구는 초기에는 Claude의 컨텍스트에 로드되지 않습니다. Claude는 Tool Search Tool 자체와 ⁠defer_loading: false⁠인 도구(가장 중요하고 자주 쓰는 도구)만 초기 컨텍스트에서 보게 됩니다.

Claude가 특정 기능이 필요할 때, 관련 도구를 검색합니다. Tool Search Tool은 일치하는 도구에 대한 참조를 반환하며, 이는 Claude의 컨텍스트에서 전체 정의로 확장됩니다.

예를 들어 Claude가 GitHub와 상호작용해야 한다면, “github”를 검색하고 ⁠github.createPullRequest⁠와 ⁠github.listIssues⁠만 로드됩니다—Slack, Jira, Google Drive의 50+ 다른 도구는 로드되지 않습니다.

이 방식으로 Claude는 전체 도구 라이브러리에 접근하면서도 실제로 필요한 도구에 대해서만 토큰 비용을 지불합니다.

프롬프트 캐싱 참고: Tool Search Tool은 지연 로드된 도구가 초기 프롬프트에서 완전히 제외되므로 프롬프트 캐싱을 저해하지 않습니다. Claude가 도구를 검색한 이후에만 컨텍스트에 추가되므로, 시스템 프롬프트와 핵심 도구 정의는 캐시 가능합니다.

구현:

{
  "tools": [
    // 도구 검색 도구 포함(정규식, BM25, 또는 커스텀)
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},

    // 온디맨드 발견 대상으로 도구 표시
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {...},
      "defer_loading": true
    }
    // ... defer_loading: true가 설정된 수백 개의 추가 지연 로드 도구
  ]
}

MCP 서버의 경우, 특정 고사용 도구는 유지하면서 전체 서버 로드를 지연할 수 있습니다:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": {"defer_loading": true}, # 전체 서버 로드를 지연합니다
  "configs": {
    "search_files": {
        "defer_loading": false
    }  // 가장 많이 사용하는 도구는 항상 로드합니다
  }
}

Claude Developer Platform은 기본 제공으로 정규식 기반과 BM25 기반 검색 도구를 제공하며, 임베딩이나 다른 전략을 사용하는 커스텀 검색 도구도 구현할 수 있습니다.

Tool Search Tool을 사용할 때

아키텍처적 결정과 마찬가지로, Tool Search Tool을 활성화하면 도구 호출 전에 검색 단계가 추가됩니다. 따라서 컨텍스트 절감과 정확도 향상이 추가 지연보다 클 때 최고의 ROI를 제공합니다.

사용하세요:

• 도구 정의가 >10K 토큰을 소비할 때
• 도구 선택 정확도 문제가 있을 때
• 여러 서버가 연결된 MCP 기반 시스템을 구축할 때
• 10개 이상의 도구가 있을 때

덜 유익합니다:

• 작은 도구 라이브러리(<10개 도구)
• 모든 도구를 매 세션에서 자주 사용하는 경우
• 도구 정의가 간결한 경우

Programmatic Tool Calling

문제

전통적인 도구 호출은 워크플로가 복잡해질수록 두 가지 근본적인 문제를 만듭니다:

• 중간 결과로 인한 컨텍스트 오염: Claude가 10MB 로그 파일에서 오류 패턴을 분석할 때, Claude는 실제로 오류 빈도 요약만 필요함에도 전체 파일이 컨텍스트 윈도우로 들어옵니다. 여러 테이블에 걸친 고객 데이터를 가져올 때, 모든 레코드가 관련성에 상관없이 컨텍스트에 누적됩니다. 이러한 중간 결과는 막대한 토큰을 소비하고 중요한 정보가 컨텍스트 윈도우에서 완전히 밀려나게 할 수 있습니다.
• 추론 오버헤드와 수동 합성: 각 도구 호출에는 전체 모델 추론 패스가 필요합니다. 결과를 받은 후, Claude는 “눈대중”으로 데이터를 추출하고, 요소들이 어떻게 맞물리는지에 대해 추론하며, 다음에 무엇을 할지 결정해야 합니다—모두 자연어 처리로요. 5개 도구 워크플로는 다섯 번의 추론 패스에 더해 Claude가 각 결과를 파싱하고, 값을 비교하고, 결론을 합성하는 과정을 의미합니다. 이는 느리고 오류가 발생하기 쉽습니다.

우리의 해결책

Programmatic Tool Calling은 개별 API 라운드트립 대신 코드로 도구를 오케스트레이션할 수 있게 합니다. Claude가 도구를 하나씩 요청하고 각 결과를 컨텍스트로 반환받는 대신, Claude는 여러 도구를 호출하고 그 출력을 처리하며 실제로 컨텍스트에 들어갈 정보를 제어하는 코드를 작성합니다.

Claude는 코드를 잘 작성하며, 오케스트레이션 로직을 자연어 도구 호출이 아닌 Python으로 표현하게 함으로써 더 신뢰할 수 있고 정확한 제어 흐름을 얻을 수 있습니다. 루프, 조건문, 데이터 변환, 에러 처리 모두 코드에서 명시적이며, Claude의 암묵적 추론에 의존하지 않습니다.

예시: 예산 준수 확인

일반적인 비즈니스 작업을 고려해봅시다: “Q3 여행 예산을 초과한 팀 구성원은 누구인가?”

세 가지 도구가 있습니다:

• ⁠get_team_members(department)⁠ - ID와 레벨을 포함하는 팀 구성원 목록 반환
• ⁠get_expenses(user_id, quarter)⁠ - 사용자별 비용 항목 반환
• ⁠get_budget_by_level(level)⁠ - 직원 레벨에 따른 예산 한도 반환

전통적 접근:

• 팀 구성원 가져오기 → 20명
• 각 사람에 대해 Q3 비용 가져오기 → 20번의 도구 호출, 각 호출은 50–100개의 항목(항공, 호텔, 식사, 영수증)을 반환
• 직원 레벨별 예산 한도 가져오기
• 이 모든 것이 Claude의 컨텍스트로 들어감: 2,000+ 비용 항목(50KB+)
• Claude가 각 사람의 비용을 수동으로 합산하고, 예산을 조회하며, 비용과 예산 한도를 비교
• 더 많은 모델 라운드트립, 상당한 컨텍스트 소비

Programmatic Tool Calling 사용 시:

각 도구 결과를 Claude에게 반환하는 대신, Claude는 전체 워크플로를 오케스트레이션하는 Python 스크립트를 작성합니다. 스크립트는 Code Execution 도구(샌드박스 환경)에서 실행되며, 여러분의 도구 결과가 필요할 때 일시중지합니다. API를 통해 도구 결과를 반환하면, 그것들은 모델이 아닌 스크립트에서 처리됩니다. 스크립트는 실행을 이어가며, Claude는 최종 출력만 보게 됩니다.

Programmatic Tool Calling은 개별 API 라운드트립 대신 코드로 도구를 오케스트레이션하며, 병렬 도구 실행을 가능하게 합니다.

예산 준수 작업에서 Claude의 오케스트레이션 코드는 다음과 같습니다:

team = await get_team_members("engineering")

# 각 고유 레벨의 예산 가져오기 
levels = list(set(m["level"] for m in team))
budget_results = await asyncio.gather(*[
    get_budget_by_level(level) for level in levels
])

# 조회용 딕셔너리 생성: {“junior”: budget1, “senior”: budget2, …}
budgets = {level: budget for level, budget in zip(levels, budget_results)}

# 모든 비용을 병렬로 가져오기
expenses = await asyncio.gather(*[
    get_expenses(m["id"], "Q3") for m in team
])

# 여행 예산을 초과한 직원 찾기
exceeded = []
for member, exp in zip(team, expenses):
    budget = budgets[member["level"]]
    total = sum(e["amount"] for e in exp)
    if total > budget["travel_limit"]:
        exceeded.append({
            "name": member["name"],
            "spent": total,
            "limit": budget["travel_limit"]
        })

print(json.dumps(exceeded))

Claude의 컨텍스트는 최종 결과만 받습니다: 예산을 초과한 2–3명의 사람들. 2,000+ 비용 항목, 중간 합계, 예산 조회는 Claude의 컨텍스트에 영향을 주지 않아, 원시 비용 데이터 200KB에서 결과 1KB로 소비를 줄입니다.

효율성 향상은 상당합니다:

• 토큰 절감: 중간 결과를 Claude의 컨텍스트 밖에 유지함으로써 PTC는 토큰 소비를 크게 줄입니다. 평균 사용량은 복잡한 조사 작업에서 43,588에서 27,297 토큰으로, 37% 감소했습니다.
• 지연 감소: 각 API 라운드트립은 모델 추론(수백 밀리초에서 수 초)을 요구합니다. Claude가 하나의 코드 블록에서 20+ 도구 호출을 오케스트레이션하면, 19+ 추론 패스를 제거합니다. API는 매번 모델로 돌아가지 않고 도구 실행을 처리합니다.
• 정확도 향상: 명시적 오케스트레이션 로직을 작성함으로써, Claude는 여러 도구 결과를 자연어로 처리할 때보다 오류가 줄어듭니다. 내부 지식 검색은 25.6%에서 28.5%로, **GIA 벤치마크**는 46.5%에서 51.2%로 개선되었습니다.

프로덕션 워크플로는 지저분한 데이터, 조건부 로직, 확장을 필요로 하는 운영을 포함합니다. Programmatic Tool Calling은 이러한 복잡성을 프로그램 방식으로 처리하면서, 원시 데이터 처리보다는 실행 가능한 결과에 집중하도록 Claude를 돕습니다.

Programmatic Tool Calling 작동 방식

1. 코드에서 호출 가능하도록 도구 표시

도구에 code_execution을 추가하고, allowed_callers를 설정하여 프로그램 방식 실행에 도구를 옵트인합니다:

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "get_team_members",
      "description": "부서의 모든 구성원을 가져옵니다…",
      "input_schema": {...},
      "allowed_callers": ["code_execution_20250825"] # 프로그램 방식 도구 호출에 옵트인
    },
    {
      "name": "get_expenses",
 	...
    },
    {
      "name": "get_budget_by_level",
	...
    }
  ]
}

API는 이러한 도구 정의를 Claude가 호출할 수 있는 Python 함수로 변환합니다.

2. Claude가 오케스트레이션 코드를 작성

개별 도구를 하나씩 요청하는 대신, Claude는 Python 코드를 생성합니다:

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc",
  "name": "code_execution",
  "input": {
    "code": "team = get_team_members('engineering')\n..." # 위의 코드 예시
  }
}

3. 도구는 Claude의 컨텍스트를 거치지 않고 실행

코드가 get_expenses()를 호출할 때, 여러분은 caller 필드가 포함된 도구 요청을 받습니다:

{
  type: "tool_use",
  id: "toolu_xyz",
  name: "get_expenses",
  input: { user_id: "emp_123", quarter: "Q3" },
  caller: {
    type: "code_execution_20250825",
    tool_id: "srvtoolu_abc",
  },
}

여러분은 결과를 제공하고, 이는 Claude의 컨텍스트가 아닌 Code Execution 환경에서 처리됩니다. 이 요청–응답 사이클은 코드의 각 도구 호출마다 반복됩니다.

4. 최종 출력만 컨텍스트로 반환

코드 실행이 완료되면, 코드의 결과만 Claude로 반환됩니다:

{
  type: "code_execution_tool_result",
  tool_use_id: "srvtoolu_abc",
  content: {
    stdout: '[{"name": "Alice", "spent": 12500, "limit": 10000}...]',
  },
}

Claude가 보는 것은 이것뿐이며, 그 과정에서 처리된 2000+ 비용 항목은 보지 않습니다.

Programmatic Tool Calling을 사용할 때

Programmatic Tool Calling은 워크플로에 코드 실행 단계를 추가합니다. 이 추가 오버헤드는 토큰 절감, 지연 개선, 정확도 향상이 상당할 때 가치가 있습니다.

가장 유익할 때:

• 집계나 요약만 필요한 대규모 데이터셋 처리
• 서로 의존하는 도구 호출이 세 단계 이상인 다단계 워크플로 실행
• Claude가 보기 전에 도구 결과를 필터링, 정렬, 변환
• 중간 데이터가 Claude의 추론에 영향을 주어서는 안 되는 작업 처리
• 여러 항목에 대한 병렬 작업(예: 50개 엔드포인트 점검)

덜 유익할 때:

• 단순한 단일 도구 호출
• 모든 중간 결과를 Claude가 보고 추론해야 하는 작업
• 응답이 작은 빠른 조회

Tool Use Examples

문제

JSON Schema는 구조—타입, 필수 필드, 허용 enum—정의에 뛰어나지만, 언제 선택적 매개변수를 포함할지, 어떤 조합이 의미 있는지, API가 기대하는 관례는 표현할 수 없습니다.

지원 티켓 API를 고려해봅시다:

{
  name: "create_ticket",
  input_schema: {
    properties: {
      title: { type: "string" },
      priority: { enum: ["low", "medium", "high", "critical"] },
      labels: { type: "array", items: { type: "string" } },
      reporter: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" },
          contact: {
            type: "object",
            properties: {
              email: { type: "string" },
              phone: { type: "string" },
            },
          },
        },
      },
      due_date: { type: "string" },
      escalation: {
        type: "object",
        properties: {
          level: { type: "integer" },
          notify_manager: { type: "boolean" },
          sla_hours: { type: "integer" },
        },
      },
    },
    required: ["title"],
  },
}

스키마는 무엇이 유효한지를 정의하지만, 중요한 질문을 남깁니다:

• 형식 모호성: ⁠due_date⁠는 “2024-11-06”, “Nov 6, 2024”, “2024-11-06T00:00:00Z” 중 무엇을 사용해야 하나요?
• ID 관례: ⁠reporter.id⁠는 UUID, “USR-12345”, 아니면 단지 “12345”인가요?
• 중첩 구조 사용: 언제 ⁠reporter.contact⁠를 채워야 하나요?
• 매개변수 상관관계: ⁠escalation.level⁠과 ⁠escalation.sla_hours⁠는 priority와 어떻게 관련되나요?

이러한 모호성은 잘못된 도구 호출과 일관성 없는 매개변수 사용으로 이어질 수 있습니다.

우리의 해결책

Tool Use Examples는 도구 정의에 샘플 도구 호출을 직접 제공할 수 있게 합니다. 스키마에만 의존하는 대신, 구체적인 사용 패턴을 Claude에게 보여줍니다:

{
  name: "create_ticket",
  input_schema: {
    /* 위와 동일한 스키마 */
  },
  input_examples: [
    {
      title: "로그인 페이지가 500 오류를 반환함",
      priority: "critical",
      labels: ["bug", "authentication", "production"],
      reporter: {
        id: "USR-12345",
        name: "Jane Smith",
        contact: {
          email: "jane@acme.com",
          phone: "+1-555-0123",
        },
      },
      due_date: "2024-11-06",
      escalation: {
        level: 2,
        notify_manager: true,
        sla_hours: 4,
      },
    },
    {
      title: "다크 모드 지원 추가",
      labels: ["feature-request", "ui"],
      reporter: {
        id: "USR-67890",
        name: "Alex Chen",
      },
    },
    {
      title: "API 문서 업데이트",
    },
  ],
}

이 세 가지 예시에서 Claude는 다음을 학습합니다:

• 형식 관례: 날짜는 YYYY‑MM‑DD, 사용자 ID는 USR‑XXXXX, 라벨은 케밥 케이스
• 중첩 구조 패턴: 연락처 중첩 객체를 포함하는 reporter 객체 구성 방법
• 선택적 매개변수 상관관계: 치명적 버그는 전체 연락처 정보 + 긴급 에스컬레이션(타이트한 SLA), 기능 요청은 reporter만 있고 연락처/에스컬레이션 없음, 내부 작업은 제목만

우리의 내부 테스트에서, Tool Use Examples는 복잡한 매개변수 처리에서 정확도를 72%에서 90%로 향상시켰습니다.

Tool Use Examples를 사용할 때

Tool Use Examples는 도구 정의에 토큰을 추가하므로, 정확도 향상이 추가 비용을 상회할 때 가장 가치가 있습니다.

가장 유익할 때:

• 유효한 JSON이 올바른 사용을 암시하지 않는 복잡한 중첩 구조
• 선택적 매개변수가 많고 포함 패턴이 중요한 도구
• 스키마로 포착되지 않는 도메인 고유 관례를 가진 API
• ⁠create_ticket⁠ vs ⁠create_incident⁠처럼 어떤 도구를 사용할지 예시가 명확히 해주는 유사 도구

덜 유익할 때:

• 명확한 사용법을 가진 단일 매개변수 도구
• Claude가 이미 이해하는 표준 형식(예: URL, 이메일)
• JSON Schema 제약으로 더 잘 처리되는 검증 문제

모범 사례

현실 세계의 행동을 수행하는 에이전트를 구축하는 일은 규모, 복잡성, 정밀성을 동시에 다루는 것을 의미합니다. 이 세 가지 기능은 도구 사용 워크플로의 서로 다른 병목을 해결하도록 함께 작동합니다. 이를 효과적으로 결합하는 방법은 다음과 같습니다.

기능을 전략적으로 레이어링

모든 에이전트가 특정 작업에 세 가지 기능을 모두 사용할 필요는 없습니다. 가장 큰 병목부터 시작하세요:

• 도구 정의로 인한 컨텍스트 팽창 → Tool Search Tool
• 컨텍스트를 오염시키는 대규모 중간 결과 → Programmatic Tool Calling
• 매개변수 오류와 잘못된 호출 → Tool Use Examples

이 집중 접근은 upfront로 복잡성을 추가하기보다, 에이전트 성능을 제한하는 특정 제약을 해결하게 합니다.

그 후 필요에 따라 추가 기능을 레이어링하세요. 이들은 상호보완적입니다: Tool Search Tool은 올바른 도구 발견을 보장하고, Programmatic Tool Calling은 효율적 실행을 보장하며, Tool Use Examples는 정확한 호출을 보장합니다.

더 나은 발견을 위한 Tool Search Tool 설정

도구 검색은 이름과 설명을 대상으로 매칭하므로, 명확하고 설명적인 정의가 검색 정확도를 높입니다.

// Good
{
    "name": "search_customer_orders",
    "description": "날짜 범위, 상태, 또는 총액으로 고객 주문을 검색합니다. 항목, 배송, 결제 정보가 포함된 주문 상세를 반환합니다."
}

// Bad
{
    "name": "query_db_orders",
    "description": "주문 쿼리 실행"
}

Claude가 무엇을 사용할 수 있는지 알도록 시스템 프롬프트 안내를 추가하세요:

Slack 메시징, Google Drive 파일 관리, Jira 티켓 추적, GitHub 리포지토리 운영을 위한 도구에 접근할 수 있습니다.
특정 기능을 찾기 위해 도구 검색을 사용하세요.

가장 자주 사용하는 3–5개의 도구는 항상 로드하고, 나머지는 지연 로드하세요. 이는 일반 작업에서의 즉시 접근성과 그 외 모든 것에 대한 온디맨드 발견을 균형 있게 제공합니다.

정확한 실행을 위한 Programmatic Tool Calling 설정

Claude가 도구 출력을 파싱하는 코드를 작성하므로, 반환 형식을 명확히 문서화하세요. 이는 정확한 파싱 로직 작성에 도움이 됩니다:

{
    "name": "get_orders",
    "description": "고객의 주문을 조회합니다.
Returns:
    주문 객체 리스트로, 각 객체는 다음을 포함합니다:
    - id (str): 주문 식별자
    - total (float): 주문 총액(USD)
    - status (str): 'pending', 'shipped', 'delivered' 중 하나
    - items (list): {sku, quantity, price} 배열
    - created_at (str): ISO 8601 타임스탬프"
}

프로그램 오케스트레이션에 적합한(옵트인할) 도구는 아래를 참고하세요:

• 병렬로 실행 가능한 도구(독립 작업)
• 재시도가 안전한(멱등) 작업

매개변수 정확도를 위한 Tool Use Examples 설정

행동적 명확성을 위해 예시를 구성하세요:

• 현실적인 데이터 사용(실제 도시 이름, 그럴듯한 가격, “string”이나 “value” 같은 플레이스홀더 지양)
• 최소·부분·완전 지정 패턴을 다양하게 보여주기
• 간결하게 유지: 도구당 1–5개 예시
• 모호성에 집중(스키마만으로 올바른 사용이 명확하지 않은 곳에만 예시 추가)

시작하기

이 기능들은 베타로 제공됩니다. 활성화하려면 베타 헤더를 추가하고 필요한 도구를 포함하세요:

client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {"type": "code_execution_20250825", "name": "code_execution"},
        # Your tools with defer_loading, allowed_callers, and input_examples
    ]
)

자세한 API 문서와 SDK 예시는 다음을 참조하세요:

• Tool Search Tool의 문서와 cookbook
• Programmatic Tool Calling의 문서와 cookbook
• Tool Use Examples의 문서

이 기능들은 단순한 함수 호출에서 지능적인 오케스트레이션으로 도구 사용을 발전시킵니다. 에이전트가 수십 개의 도구와 대규모 데이터셋에 걸친 더 복잡한 워크플로를 처리함에 따라, 동적 발견, 효율적인 실행, 신뢰할 수 있는 호출이 핵심이 됩니다.

무엇을 구축하실지 기대하고 있습니다.