Claude 가이드 #22: 도구 검색 — 수천 개 중에서 필요한 것만 꺼내 쓰기

이 글은 Claude API 공식 문서의 Tool search tool 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool 마지막 확인: 2026-06-01

1. 한 줄 요약
#

Claude에게 도구 목록을 통째로 보여주지 마세요. 필요할 때 검색해서 꺼내 쓰게 하면 더 정확해지고 비용도 줄어듭니다.

2. 무엇이고 왜 좋을까
#

큰 도서관에서 한 권을 빌리는 것과 같습니다. 입구에 책 만 권을 쌓아두지 않고, 검색대에서 필요한 책 몇 권만 꺼내 주는 방식입니다.

Claude는 “도구(tool)” — 날씨를 알아오거나, 파일을 찾거나, 메시지를 보내는 작은 기능들 — 을 쓸 수 있습니다. 그런데 도구를 너무 많이 알려주면 두 가지 문제가 생깁니다. 첫째, 도구 설명만으로 Claude가 읽어야 할 글이 한참 길어집니다. 한 보고서에 따르면 다섯 군데 서비스만 연결해도 도구 설명에 약 5만 5천 토큰(AI가 글자를 세는 단위)이 쓰입니다. 둘째, 도구가 30~50개를 넘어가면 Claude가 “어떤 도구를 써야 하지?” 하고 헷갈리기 시작합니다.

도구 검색(Tool Search) 은 이걸 해결합니다. 도구 목록을 처음부터 다 보여주는 대신, Claude가 필요할 때 검색해서 3~5개만 꺼내 옵니다. 평균적으로 도구 설명에 쓰이는 분량을 85% 이상 줄여줍니다.

3. 이런 상황에서 써요
#

상황 1: 학생의 만능 학습 도우미
#

“수업마다 다른 도구가 필요해요. 수학 시간엔 계산기, 영어 시간엔 사전, 역사 시간엔 연표 검색, 과학 시간엔 단위 변환기. 이걸 한 번에 다 켜놓으면 AI가 자꾸 엉뚱한 걸 골라요.”

도구 검색을 켜두면 Claude가 질문을 보고 알아서 고릅니다. “이 적분 좀 풀어줘"라고 하면 계산기를 꺼내고, “이 영어 문장 뉘앙스 알려줘"라고 하면 사전을 꺼냅니다. 학생은 그냥 평소처럼 물어보기만 하면 됩니다.

상황 2: 회사 내부 비서
#

“우리 회사는 일정표, 휴가 신청, 회의실 예약, 사내 메신저, 매뉴얼 검색 같은 시스템이 다 따로 있어요. 직원들이 ‘AI 한 명한테 다 물어보면 좋겠다’고 해서 연결해뒀는데, 도구가 50개를 넘으니 AI가 헤매기 시작했어요.”

도구 검색을 켜면 직원이 “다음 주 화요일 회의실 비어?“라고 했을 때 Claude가 회의실 예약 도구만 골라서 씁니다. “지난달 매출 보고서 어디 있어?“라고 하면 문서 검색 도구를 꺼냅니다. 사람이 시스템을 외울 필요가 없어집니다.

상황 3: 취미 생활 정리함
#

“저는 가계부, 독서 기록, 운동 일지, 레시피 모음을 따로 쓰고 있어요. 매번 어디에 적어야 할지 까먹어요.”

각 기록 도구를 Claude에게 등록해두면 됩니다. “오늘 점심에 5천 원 썼어"라고 하면 가계부에, “오늘 30분 달렸어"라고 하면 운동 일지에 알아서 적습니다. 도구를 많이 등록해도 그때그때 필요한 것만 꺼내 쓰니까 속도도 비용도 부담이 적습니다.

4. 가볍게 시작하기
#

💻 개발 경험 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “아, 이런 식으로 쓰는구나” 정도로 보고 넘어가셔도 좋습니다.

import anthropic
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[{"role": "user", "content": "샌프란시스코 날씨 알려줘"}],
    tools=[
        # 도구 검색 기능 자체를 켜는 한 줄
        {"type": "tool_search_tool_regex_20251119",
         "name": "tool_search_tool_regex"},

        # 날씨 도구 — 평소엔 숨겨두기
        {
            "name": "get_weather",
            "description": "특정 지역의 현재 날씨를 알려줍니다",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,  # ← 이 한 줄이 '필요할 때만 꺼내기'
        },
        # 다른 도구들도 같은 방식으로 defer_loading: True 로 등록
    ],
)
print(response)

핵심은 두 줄입니다. 위쪽 tool_search_tool_regex_20251119로 검색 기능을 켜고, 각 도구마다 defer_loading: True를 붙여서 “평소엔 숨겨둬"라고 표시합니다. 그러면 Claude가 질문을 보고 필요한 도구만 검색해서 꺼내 씁니다. 첫 줄에 검색 도구를 깜빡 빼먹지 마세요 — 그게 안 켜져 있으면 숨겨둔 도구를 찾을 방법이 없어집니다.

5. 흔한 오해와 함정
#

⚠️ 함정 1: “도구를 다 숨겨버리면 되겠지?”
#

처음 보면 “모든 도구를 defer_loading: True로 해야 가장 효율적이겠다"라고 생각하기 쉽습니다. 그런데 도구를 전부 숨기면 오류가 납니다. 적어도 하나는 평소에 보이는 상태로 둬야 합니다. 추천은 자주 쓰는 도구 3~5개는 안 숨기는 것입니다. 매번 검색하는 시간도 줄고, 결과도 안정적입니다.

⚠️ 함정 2: “도구 이름만 잘 지으면 되겠지?”
#

도구 검색은 이름뿐 아니라 설명문, 인자 이름, 인자 설명까지 다 뒤져봅니다. 그래서 get_data 같이 막연한 이름보다 get_weather 처럼 구체적인 이름이 좋고, 설명에는 사람들이 쓸 법한 단어를 같이 넣어주는 게 좋습니다. 예를 들어 “날씨, 기온, 강수량을 알려줍니다"라고 적어두면 “비 올까?“라는 질문에도 잘 잡힙니다.

⚠️ 함정 3: “검색어를 자연스럽게 쓰면 되지 않나?”
#

도구 검색에는 두 종류가 있습니다. tool_search_tool_regex_20251119는 정규식(regex, 글자 패턴 찾는 문법)으로 검색하고, tool_search_tool_bm25_20251119는 자연어로 검색합니다. 어, 그런데 왜 안 되지? 싶을 때 보면 regex 버전을 켜둔 채로 “날씨 알려주는 거"라고 검색되길 기대하고 있더라, 같은 경우가 있습니다. 잘 모르겠으면 입문자에게는 BM25(자연어 버전) 가 더 편합니다.

6. 한 단계 더 (관심 있는 분만)
#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.

도구가 늘어날수록 도구 검색이 얼마나 절약해주는지 감을 잡아보겠습니다. 다음은 대략적인 비교입니다.

도구 개수	도구 검색 X	도구 검색 O	절감
10개	약 5천 토큰	약 1천 토큰	80%
50개	약 2.5만 토큰	약 2천 토큰	92%
200개	약 10만 토큰 (한도 초과 위험)	약 3천 토큰	97%

참고: 위 수치는 도구 하나당 설명이 500토큰 정도라고 가정한 어림셈입니다. 실제로는 도구 설명 길이에 따라 달라집니다.

그리고 한 가지 더. 한 번 검색된 도구는 같은 대화 안에서 다시 검색하지 않습니다. 즉, 사용자가 “샌프란시스코 날씨"를 묻고 이어서 “그럼 도쿄는?“이라고 하면, 두 번째 질문에는 검색 과정 없이 바로 날씨 도구를 씁니다. 캐시(잠깐 기억해두기) 도 그대로 유지되니까 추가 비용 걱정도 줄어듭니다.

도구가 10개 미만이고 매번 다 쓴다면 굳이 도구 검색을 켤 필요는 없습니다. “10개 이상이거나 도구 설명이 1만 토큰 넘게 들어간다” 정도가 적용해볼 만한 기준입니다.