--- title: 도구 레퍼런스 url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference description: Anthropic이 제공하는 서버 도구, 클라이언트 도구, 클라이언트 도구 세트의 디렉터리와 선택적 도구 정의 속성에 대한 레퍼런스입니다. --- 이 페이지는 Anthropic이 제공하는 도구와 모든 도구 정의에 설정할 수 있는 선택적 속성에 대한 레퍼런스입니다. "tool use"(도구 사용)에 대한 개념적 소개는 [Claude와 함께하는 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)을 참조하세요. 애플리케이션에서 도구 사용을 구현하는 방법에 대한 안내는 [도구 정의하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools)를 참조하세요. ## Anthropic 제공 도구 Anthropic은 두 가지 종류의 도구를 제공합니다. Anthropic의 인프라에서 실행되는 **서버 도구**와, Anthropic이 스키마를 정의하지만 실행은 여러분의 애플리케이션이 처리하는 **클라이언트 도구**입니다. 두 종류 모두 사용자 정의 도구와 함께 요청의 `tools` 배열에 포함됩니다. | 도구 | `type` | 실행 | [베타 헤더](https://platform.claude.com/docs/ko/api/beta-headers) | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------- | | [웹 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-search-tool) | `web_search_20260318`
`web_search_20260209`
`web_search_20250305` | 서버 | 없음 | | [웹 페치 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool) | `web_fetch_20260318`
`web_fetch_20260309`
`web_fetch_20260209`
`web_fetch_20250910` | 서버 | 없음 | | [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool) | `code_execution_20260521`
`code_execution_20260120`
`code_execution_20250825` | 서버 | 없음 | | [어드바이저 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool) | `advisor_20260301` | 서버 | `advisor-tool-2026-03-01` | | [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool) | `tool_search_tool_regex_20251119`
`tool_search_tool_bm25_20251119` | 서버 | 없음 | | [MCP 커넥터](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector) | `mcp_toolset` | 서버 | `mcp-client-2025-11-20` | | [메모리 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/memory-tool) | `memory_20250818` | 클라이언트 | 없음 | | [Bash 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/bash-tool) | `bash_20250124` | 클라이언트 | 없음 | | [텍스트 편집기 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/text-editor-tool) | `text_editor_20250728`
`text_editor_20250124` | 클라이언트 | 없음 | | [컴퓨터 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool) | `computer_toolset_20260801`
`computer_20251124`
`computer_20250124` | 클라이언트 | 없음
`computer-use-2025-11-24`
`computer-use-2025-01-24` | | [브라우저 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool) | `browser_toolset_20260801` | 클라이언트 | 없음 | 모델 호환성은 각 도구의 페이지를 참조하세요. 지원되는 모델은 도구 및 도구 버전에 따라 다릅니다. 코드에서 모델이 웹 검색 또는 코드 실행을 허용하는지 확인하려면 [Models API 사용하기](https://platform.claude.com/docs/ko/models/overview#using-the-models-api)를 참조하세요. 도구 검색 `type` 값은 날짜가 없는 별칭인 `tool_search_tool_regex` 및 `tool_search_tool_bm25`도 허용합니다. 이들은 최신 날짜 버전으로 해석됩니다. ### 도구 버전 관리 대부분의 Anthropic 제공 도구는 `type` 문자열에 `_YYYYMMDD` 접미사를 가집니다. 도구의 동작, 스키마 또는 모델 지원이 변경되면 새 버전이 릴리스됩니다. 기존 통합이 계속 작동하도록 이전 버전도 계속 사용할 수 있습니다. 도구에 여러 활성 버전이 있는 경우, 버전 간의 관계는 다양합니다. * **기능 기반:** `web_search_20260209`와 `web_fetch_20260209`는 이전 버전에 비해 동적 콘텐츠 필터링을 추가합니다. `web_fetch_20260309`는 캐시 우회 옵션을 추가하고, `web_search_20260318`과 `web_fetch_20260318`은 응답 포함 제어를 추가합니다. `code_execution_20260120`은 샌드박스 내에서의 [프로그래매틱 도구 호출](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/programmatic-tool-calling)을 추가하고, `code_execution_20260521`은 도구 설명에 셀당 시간 제한을 명시합니다. 각 경우 새 버전과 이전 버전 모두 현재 버전이며, 어떤 버전을 사용할지는 새 기능이 필요한지 여부에 따라 달라집니다. * **모델 기반:** `text_editor_20250728`은 Claude 4 이상 모델용이고 `text_editor_20250124`는 이전 모델용입니다. 사용할 버전은 대상 모델에 따라 달라집니다. * **버전이 아닌 변형:** `tool_search_tool_regex_20251119`와 `tool_search_tool_bm25_20251119`는 함께 출시된 두 가지 검색 알고리즘입니다. 어느 쪽도 다른 쪽을 대체하지 않습니다. * **레거시:** `code_execution_20250522`는 Python만 지원합니다. `code_execution_20250825`는 Bash 및 파일 작업을 추가합니다. * **후속 버전:** `computer_toolset_20260801`은 베타 버전인 `computer_20251124` 및 `computer_20250124`의 안정적인 후속 버전이며, 이 베타 버전들은 [이전 도구 버전](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions)에 나열된 모델에서 계속 사용할 수 있습니다. `browser_toolset_20260801`은 브라우저 사용 도구의 첫 번째 버전입니다. 둘 다 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)입니다. `mcp_toolset` 타입은 날짜로 버전이 지정되지 않으며, 대신 `anthropic-beta` 헤더로 버전이 관리됩니다. ### 클라이언트 도구 세트 [컴퓨터 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool)와 [브라우저 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool)는 Anthropic이 정의한 "client toolsets"(클라이언트 도구 세트)입니다. `tools`의 항목 하나가 Anthropic이 이름, 설명, 입력 스키마를 정의한 고정된 멤버 도구 집합을 선언하며, 모든 호출은 여러분의 애플리케이션이 실행합니다. 날짜가 지정된 `type`이 멤버 이름을 고정하므로 이 항목은 `name`을 받지 않습니다. `configs`, `cache_control`, `allowed_callers`(`["direct"]`만 허용)는 선택 사항입니다. 클라이언트 도구 세트는 Messages API 도구입니다. 현재 [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/tools)에서는 에이전트 도구로 사용할 수 없으며, Claude Managed Agents는 자체 내장 에이전트 도구 세트, MCP 도구 세트, 커스텀 도구를 제공합니다. ```json { "type": "browser_toolset_20260801", "configs": { "javascript_exec": { "enabled": true } }, "cache_control": { "type": "ephemeral" } } ``` `configs`는 개별 멤버를 조정합니다. * 키는 멤버 이름이며, 각 값은 `enabled`와 `defer_loading`만 허용합니다. * 생략한 멤버는 기본값을 유지합니다. 값이 없는 경우, `{}`, 기본값을 다시 명시한 경우는 모두 동일합니다. * 알 수 없는 멤버 이름이나 멤버 값의 다른 필드는 거부되며, 모든 멤버를 비활성화하는 `configs`도 거부됩니다(대신 항목을 생략하세요). * 비활성화된 멤버는 Claude가 보는 도구에서 제거됩니다. Claude가 여전히 해당 멤버를 지정하면 오류 `tool_result`를 반환하세요. `defer_loading`은 항목이 아닌 멤버별로 설정하고, 활성화된 모든 멤버에 동일한 값을 지정하세요. [도구 검색](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading)에서 도구 세트는 하나의 정의로 로드되고 확장됩니다. 활성화된 모든 멤버가 지연 로드되는 경우, 자체적으로 지연되지 않은 [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool)만이 도구 세트를 노출할 수 있으므로 같은 요청에 하나를 선언하세요. 멤버가 지연 로드되는 도구 세트 항목에는 `cache_control`을 두지 마세요. 지연된 정의는 캐시된 접두사의 일부가 아니므로, 대신 지연되지 않은 도구에 중단점을 설정하세요. `cache_control`은 항목에만 설정합니다. 배치 액션 내부의 마커를 포함하여 중단점이 어디에 위치하는지 알아보려면 [프롬프트 캐싱과 함께하는 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)을 참조하세요. **멤버 도구 호출 처리.** Claude는 `name`이 멤버 이름이고 `toolset_name`이 `computer` 또는 `browser`인 `tool_use` 블록으로 멤버를 호출합니다. `input`에는 해당 멤버의 매개변수가 담기며 `action` 필드는 없습니다. 커스텀 도구가 멤버와 이름을 공유할 수 있고 두 도구 세트가 `screenshot` 같은 이름을 공유하므로, `toolset_name`과 `name` 쌍을 기준으로 디스패치하세요. 멤버 결과만 `toolset_name`을 되돌려 줍니다. 한 턴에서 여러 멤버 호출은 순서대로 실행하는 배치 액션을 형성합니다([컴퓨터 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#batch-actions), [브라우저 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool#batch-actions)). 새 멤버는 새로운 날짜의 `type`과 함께만 추가됩니다. **도구 세트 항목에서 지원되지 않는 사항.** API는 다음 각각을 `invalid_request_error`로 거부합니다. * `strict: true` 또는 `input_examples`. * 항목에 설정된 `defer_loading`, 또는 `defer_loading` 값이 서로 다른 활성화된 멤버들(`configs`에서 멤버별로, 모두 같은 값으로 설정하세요). * `allowed_callers`의 코드 실행 호출자([프로그래매틱 도구 호출](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/programmatic-tool-calling) 불가). * 레거시 `fine-grained-tool-streaming-2025-05-14` 베타 헤더. 스트리밍 시 각 멤버의 `input`은 하나의 완전한 `input_json_delta`로 도착합니다. * 도구 세트나 멤버를 지정하는 `tool` 타입의 `tool_choice`(`auto`, `any` 또는 `none`을 사용하세요). * 동일한 도구 세트의 항목 두 개, 또는 해당 도구 세트의 이름을 가진 다른 도구: `computer_toolset_20260801`과 함께 `computer`라는 이름의 도구, 또는 `browser_toolset_20260801`과 함께 `browser`라는 이름의 도구. 두 도구 세트는 함께 선언할 수 있습니다. ## 도구 정의 속성 사용자 정의 도구를 포함하여 `tools` 배열의 모든 도구는 도구가 로드되는 방식, 호출할 수 있는 주체, 입력 검증 방식을 제어하는 선택적 속성을 허용합니다. 이러한 속성은 조합할 수 있습니다. 같은 도구에 `defer_loading`, `cache_control`, `strict`를 함께 설정할 수 있습니다. | 속성 | 목적 | 사용 가능 대상 | 상세 가이드 | | ----------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `cache_control` | 이 도구 정의에 프롬프트 캐시 중단점 설정 | 모든 도구(`computer_toolset_20260801` 및 `browser_toolset_20260801`에서는 멤버 `configs` 내부가 아닌 도구 세트 항목 자체에 설정) | [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) | | `strict` | 도구 이름과 입력에 대한 스키마 검증 보장 | `mcp_toolset`, `computer_toolset_20260801`, `browser_toolset_20260801`을 제외한 모든 도구 | [엄격한 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use) | | `defer_loading` | 초기 시스템 프롬프트에서 도구를 제외하고, 도구 검색이 해당 도구에 대한 `tool_reference`를 반환할 때 필요에 따라 로드 | 모든 도구(`mcp_toolset`의 경우 [도구 구성](https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector#mcp-toolset-configuration) 참조). 컴퓨터 사용 및 브라우저 사용 도구 세트에서는 `configs` 내부에서 멤버별로 설정합니다. [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets)를 참조하세요. | [도구 검색 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool) | | `allowed_callers` | 도구를 호출할 수 있는 호출자 제한 | `mcp_toolset`을 제외한 모든 도구(`computer_toolset_20260801` 및 `browser_toolset_20260801`에서는 `["direct"]`만 허용됩니다. [클라이언트 도구 세트](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference#client-toolsets) 참조) | [프로그래매틱 도구 호출](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field) | | `input_examples` | Claude가 도구 호출 방법을 이해하도록 돕는 예시 입력 객체 제공 | `computer_toolset_20260801` 및 `browser_toolset_20260801`을 제외한 사용자 정의 도구 및 Anthropic 스키마 클라이언트 도구. 서버 도구에서는 사용할 수 없습니다. | [도구 정의하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) | | `eager_input_streaming` | 이 도구에 대해 세분화된 입력 스트리밍 활성화(`true`) 또는 표준 버퍼링 스트리밍 유지(`false`) | 사용자 정의 도구만 | [세분화된 도구 스트리밍](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/fine-grained-tool-streaming) | ### `allowed_callers` 값 `allowed_callers`는 다음의 임의 조합을 허용하는 배열입니다. | 값 | 의미 | | --------------------------- | -------------------------------------------------------------------------- | | `"direct"` | 모델이 `tool_use` 블록에서 이 도구를 직접 호출할 수 있습니다. `allowed_callers`가 생략된 경우 기본값입니다. | | `"code_execution_20260120"` | `code_execution_20260120` 또는 이후 버전의 샌드박스 내부에서 실행되는 코드가 이 도구를 호출할 수 있습니다. | `"code_execution_20260120"`과 `"code_execution_20260521"` 모두 `allowed_callers`에서 허용되며 서로 교환 가능합니다. 어느 코드 실행 도구 버전을 사용하는 요청이든 어느 호출자를 나열한 도구든 충족합니다. 응답 블록은 요청이 선언한 버전과 관계없이 항상 호출자를 `code_execution_20260120`으로 태그합니다. 배열에서 `"direct"`를 생략하면(예: `"allowed_callers": ["code_execution_20260120"]`) Claude가 코드 실행 내부에서만 도구를 호출하도록 유도합니다. 응답의 `tool_use` 블록에는 어떤 호출자가 도구를 호출했는지 식별하는 `caller` 필드가 포함됩니다. `caller` 응답 형태와 오류 동작을 포함한 전체 내용은 [프로그래매틱 도구 호출](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field)을 참조하세요. ### `defer_loading`과 프롬프트 캐싱 `defer_loading: true`인 도구는 캐시 키가 계산되기 전에 렌더링된 도구 섹션에서 제거됩니다. 시스템 프롬프트 접두사에 전혀 나타나지 않습니다. 도구 검색이 지연된 도구를 발견하고 해당 도구에 대한 `tool_reference`를 반환하면, 도구의 전체 정의는 접두사가 아닌 대화 본문의 해당 지점에서 인라인으로 확장됩니다. 이는 `defer_loading: true`가 프롬프트 캐시를 보존한다는 것을 의미합니다. 기존 캐시 항목을 무효화하지 않고 요청에 지연된 도구를 추가할 수 있으며, 도구가 발견되는 턴과 호출되는 턴에 걸쳐 캐시가 유효하게 유지됩니다. `defer_loading`을 `cache_control` 중단점과 결합하는 방법을 알아보려면 [도구 검색 도구 프롬프트 캐싱 안내](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#prompt-caching)를 참조하세요.