도구 레퍼런스 (Tool Reference)¶
이 페이지는 Anthropic이 제공하는 도구들과, 모든 도구 정의에 설정할 수 있는 선택 속성(optional properties)에 대한 레퍼런스예요. 도구 사용에 대한 개념적인 소개는 Tool use with Claude 문서를, 애플리케이션에서 도구 사용을 구현하는 방법은 Define tools 문서를 참고하세요.
Anthropic 제공 도구¶
Anthropic이 제공하는 도구에는 두 종류가 있어요. 서버 도구(server tools)는 Anthropic의 인프라 위에서 실행되고, 클라이언트 도구(client tools)는 Anthropic이 스키마를 정의하되 실행은 여러분의 애플리케이션이 담당하죠. 두 종류 모두 요청의 tools 배열에 사용자 정의 도구와 함께 들어갑니다.
| 도구 | type |
실행 | Beta 헤더 |
|---|---|---|---|
| Web search tool | web_search_20260318web_search_20260209web_search_20250305 |
서버 | 없음 |
| Web fetch tool | web_fetch_20260318web_fetch_20260309web_fetch_20260209web_fetch_20250910 |
서버 | 없음 |
| Code execution tool | code_execution_20260521code_execution_20260120code_execution_20250825 |
서버 | 없음 |
| Advisor tool | advisor_20260301 |
서버 | advisor-tool-2026-03-01 |
| Tool search tool | tool_search_tool_regex_20251119tool_search_tool_bm25_20251119 |
서버 | 없음 |
| MCP connector | mcp_toolset |
서버 | mcp-client-2025-11-20 |
| Memory tool | memory_20250818 |
클라이언트 | 없음 |
| Bash tool | bash_20250124 |
클라이언트 | 없음 |
| Text editor tool | text_editor_20250728text_editor_20250124 |
클라이언트 | 없음 |
| Computer use tool | computer_toolset_20260801computer_20251124computer_20250124 |
클라이언트 | 없음computer-use-2025-11-24computer-use-2025-01-24 |
| Browser use tool | browser_toolset_20260801 |
클라이언트 | 없음 |
모델 호환성은 각 도구의 페이지를 참고하세요. 지원되는 모델은 도구별·도구 버전별로 달라요.
도구 버전 관리¶
대부분의 Anthropic 제공 도구는 type 문자열에 _YYYYMMDD 접미사를 답니다. 도구의 동작, 스키마, 또는 모델 지원이 바뀌면 새 버전이 출시되고, 기존 통합이 계속 동작하도록 이전 버전도 함께 유지됩니다.
도구에 활성 버전이 여럿 있을 때, 버전 사이의 관계는 경우에 따라 달라져요.
- 기능 기준(Capability-keyed):
web_search_20260209와web_fetch_20260209는 이전 버전에 비해 동적 콘텐츠 필터링을 추가하고,web_fetch_20260309는 캐시 우회 옵션을,web_search_20260318과web_fetch_20260318은 응답 포함 제어(response-inclusion control)를 추가해요.code_execution_20260120은 샌드박스 안에서 프로그래매틱 도구 호출을 지원하고,code_execution_20260521은 셀별 시간 제한을 도구 설명에 공개해요. 이 경우 새 버전과 옛 버전 모두 현재 버전이고, 새 기능이 필요한지에 따라 어느 쪽을 쓸지 정하면 됩니다. - 모델 기준(Model-keyed):
text_editor_20250728은 Claude 4 이후 모델용이고,text_editor_20250124는 이전 모델용이에요. 어떤 버전을 쓸지는 대상 모델에 따라 달라집니다. - 변형이지 버전이 아님(Variant, not version):
tool_search_tool_regex_20251119와tool_search_tool_bm25_20251119는 함께 출시된 두 가지 검색 알고리즘이에요. 어느 하나가 다른 하나를 대체하지 않습니다. - 레거시(Legacy):
code_execution_20250522는 Python만 지원해요.code_execution_20250825는 Bash와 파일 작업을 추가합니다. - 후속 버전(Successor):
computer_toolset_20260801은 베타 버전인computer_20251124와computer_20250124의 안정적인 후속 버전이에요. 두 이전 버전은 기존 통합과 툴셋을 지원하지 않는 모델을 위해 계속 사용할 수 있습니다(이전 도구 버전).browser_toolset_20260801은 브라우저 사용 도구의 첫 번째 버전이에요. 둘 다 클라이언트 툴셋입니다.
mcp_toolset type은 날짜 기반 버전을 사용하지 않아요. 대신 버전 관리를 anthropic-beta 헤더가 담당합니다.
클라이언트 툴셋¶
컴퓨터 사용 도구와 브라우저 사용 도구는 Anthropic이 정의하는 클라이언트 툴셋이에요. tools의 항목 하나가 고정된 멤버 도구 묶음을 선언하는데, 멤버 도구의 이름·설명·입력 스키마는 모두 Anthropic이 정의하고 실행은 여러분의 애플리케이션이 담당하죠. 이 항목에는 name을 쓰지 않는데, 날짜가 붙은 type이 멤버 이름을 고정하기 때문이에요. configs, cache_control, 그리고 ["direct"]만 받는 allowed_callers는 모두 선택 항목입니다.
클라이언트 툴셋은 Messages API 도구예요. 자체 내장 에이전트 툴셋, MCP 툴셋, 커스텀 도구를 제공하는 Claude Managed Agents에서는 아직 에이전트 도구로 쓸 수 없습니다.
{
"type": "browser_toolset_20260801",
"configs": {
"javascript_exec": { "enabled": true }
},
"cache_control": { "type": "ephemeral" }
}
configs는 개별 멤버를 조정해요.
- 키는 멤버 이름이고, 각 값은
enabled와defer_loading만 받습니다. - 생략한 멤버는 기본값을 유지해요. 값이 아예 없거나
{}이거나 기본값을 다시 적은 것은 모두 동일하게 취급됩니다. - 알 수 없는 멤버 이름이나 멤버 값의 다른 필드는 거부되고,
configs가 모든 멤버를 비활성화하는 경우도 거부됩니다(대신 항목 자체를 생략하세요). - 비활성화된 멤버는 Claude가 보는 도구 목록에서 빠져요. 그래도 Claude가 그 멤버를 호출하면
tool_result로 오류를 돌려주세요.
defer_loading은 항목이 아니라 멤버별로 설정하고, 활성화된 모든 멤버에 같은 값을 주세요. 도구 검색에서는 툴셋이 하나의 정의로 로드·확장되기 때문이에요. 활성화된 멤버가 모두 defer되면, 그 툴셋을 표면화할 수 있는 것은 자기 자신이 defer되지 않은 도구 검색 도구뿐이므로 같은 요청에 하나를 선언해 두세요. 멤버가 defer되는 툴셋 항목에는 cache_control을 두지 마세요. 대신 defer되지 않은 도구에 브레이크포인트를 설정하세요. defer된 정의는 캐시된 프리픽스에 포함되지 않기 때문이에요.
cache_control은 항목에만 붙습니다. 브레이크포인트가 어디에 찍히는지(배치 액션 안의 마커 포함)는 프롬프트 캐싱과 도구 사용 문서를 참고하세요.
멤버 도구 호출 처리하기. Claude가 멤버를 호출하면 tool_use 블록이 오는데, name은 멤버 이름이고 toolset_name은 computer 또는 browser이며, input은 해당 멤버의 파라미터를 담고 action 필드는 없어요. toolset_name과 name의 쌍으로 분기하세요. 커스텀 도구가 멤버와 이름을 공유할 수 있고, 두 툴셋은 screenshot 같은 이름을 공유하기 때문이에요. 멤버 결과에만 toolset_name이 실려 옵니다. 한 턴 안의 여러 멤버 호출은 순서대로 실행하는 배치 액션을 이룹니다(컴퓨터 사용, 브라우저 사용). 새 멤버는 새 날짜 type과 함께만 추가됩니다.
툴셋 항목에서 지원하지 않는 것. 다음 각각은 API가 invalid_request_error로 거부해요.
strict: true또는input_examples.- 항목에 붙인
defer_loading, 또는defer_loading값이 다른 활성 멤버(configs에서 멤버별로, 모두 같은 값으로 설정하세요). allowed_callers의 코드 실행 호출자(프로그래매틱 도구 호출 없음).- 레거시
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 안이 아니라 툴셋 항목 자체에 설정) |
프롬프트 캐싱 |
strict |
도구 이름과 입력에 대한 스키마 검증 보장 | mcp_toolset, computer_toolset_20260801, browser_toolset_20260801을 제외한 모든 도구 |
Strict tool use |
defer_loading |
도구를 초기 시스템 프롬프트에서 제외하고, 도구 검색이 tool_reference를 반환하면 그때 로드 |
모든 도구(mcp_toolset은 도구 설정 참고). 컴퓨터 사용·브라우저 사용 툴셋에서는 configs 안에서 멤버별로 설정 — 클라이언트 툴셋 참고 |
도구 검색 도구 |
allowed_callers |
도구를 호출할 수 있는 호출자 제한 | mcp_toolset을 제외한 모든 도구(computer_toolset_20260801과 browser_toolset_20260801에서는 ["direct"]만 허용 — 클라이언트 툴셋 참고) |
프로그래매틱 도구 호출 |
input_examples |
Claude가 도구를 호출하는 방법을 이해하도록 예제 입력 객체 제공 | 사용자 정의 도구와 Anthropic 스키마 클라이언트 도구(단, computer_toolset_20260801과 browser_toolset_20260801 제외). 서버 도구에서는 사용 불가 |
도구 정의 |
eager_input_streaming |
이 도구에 대해 세밀한 입력 스트리밍(true)을 켜거나 표준 버퍼드 스트리밍(false)을 유지 |
사용자 정의 도구만 | 세밀한 도구 스트리밍 |
allowed_callers 값¶
allowed_callers는 배열이고, 다음의 어떤 조합도 받아요.
| 값 | 의미 |
|---|---|
"direct" |
모델이 tool_use 블록에서 이 도구를 직접 호출할 수 있음. allowed_callers를 생략하면 기본값입니다. |
"code_execution_20260120" |
code_execution_20260120 이후 샌드박스 안에서 실행되는 코드가 이 도구를 호출할 수 있음. |
allowed_callers에는 "code_execution_20260120"과 "code_execution_20260521" 둘 다 허용되고 서로 바꿔 쓸 수 있어요. 두 코드 실행 도구 버전 중 어느 것으로 한 요청이라도 두 호출자 중 어느 쪽을 나열하는 도구를 충족시킵니다. 응답 블록은 요청이 선언한 버전과 무관하게 항상 호출자를 code_execution_20260120으로 표시해요.
배열에서 "direct"를 빼면(예: "allowed_callers": ["code_execution_20260120"]) Claude가 이 도구를 코드 실행 안에서만 호출하도록 유도합니다. 응답의 tool_use 블록에는 어떤 호출자가 도구를 호출했는지 알려주는 caller 필드가 포함됩니다. caller 응답 모양과 오류 동작을 포함한 전체 설명은 프로그래매틱 도구 호출 문서를 참고하세요.
defer_loading과 프롬프트 캐싱¶
defer_loading: true인 도구는 캐시 키가 계산되기 전에 렌더링된 도구 섹션에서 빠져요. 시스템 프롬프트 프리픽스에는 아예 나타나지 않죠. 도구 검색이 defer된 도구를 발견하고 tool_reference를 반환하면, 그 도구의 전체 정의는 프리픽스가 아니라 대화 본문의 그 지점에 인라인으로 확장됩니다.
즉 defer_loading: true는 프롬프트 캐시를 보존해 줘요. defer된 도구를 요청에 추가하더라도 기존 캐시 항목이 무효화되지 않고, 도구가 발견된 턴과 호출된 턴에 걸쳐 캐시도 유효하게 유지됩니다.
defer_loading과 cache_control 브레이크포인트를 어떻게 조합하는지는 도구 검색 도구 프롬프트 캐싱 가이드를 참고하세요.