SIGNAL-COST-250. 사용 가능한 도구 수가 늘어나면 실제 작업을 시작하기도 전에 스키마 자체가 컨텍스트를 잠식한다. 도구 정의의 입력 토큰 부담과 검색 왕복을 함께 비교해야 한다. 특정 도구 개수나 절감률을 모든 구성에 적용할 수는 없다. 이 두 문제를 동시에 푸는 게 Tool Search tool과 defer_loading 파라미터다.
Tool Search는 어떻게 동작하는가
전체 도구 정의를 매 요청마다 앞단에 다 넣는 대신, 도구 이름·설명·인자명·인자 설명을 검색 대상으로 삼아 필요한 도구만 그때그때 불러오는 방식이다. tools 배열에는 모든 도구 정의를 여전히 포함시키되, 처음부터 로드하지 않을 도구에는 defer_loading: true를 붙인다. 최소 하나(보통 tool search 도구 자신)는 지연 로딩 대상에서 제외해야 한다.
- 초기 컨텍스트에는 tool search 도구와 지연 로딩되지 않은 도구만 들어간다.
- Claude가 추가 도구가 필요하다고 판단하면 검색을 실행한다.
- API가 검색을 수행하고 일치하는 도구를
tool_reference블록으로 반환한다(기본 최대 5개, Claude가limit으로 조정 가능). - API가 이 참조를 전체 도구 정의로 자동 확장한다.
- Claude가 확장된 도구 중에서 골라 호출한다.
검색 방식은 두 가지다. tool_search_tool_regex_20251119는 Claude가 정규식 패턴을 만들어 검색하고, tool_search_tool_bm25_20251119는 자연어 질의로 검색한다. 공식 문서의 검색 결과 기본 상한은 다섯 개다. 이것은 전체 작업에서 쓰는 도구 수나 보장된 토큰 절감률을 뜻하지 않는다. 구성과 요청에 따라 실제 검색 횟수와 로드되는 정의가 달라진다.
defer_loading 설정 예시
{
"tools": [
{ "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" },
{
"name": "get_weather",
"description": "Get the weather at a specific location",
"input_schema": { "type": "object", "properties": { "location": {"type": "string"} }, "required": ["location"] },
"defer_loading": true
},
{
"name": "search_files",
"description": "Search through files in the workspace",
"input_schema": { "type": "object", "properties": { "query": {"type": "string"} }, "required": ["query"] },
"defer_loading": true
}
]
}여기서 get_weather, search_files의 정의는 서버에 전달되지만 초기 모델 컨텍스트에는 로드되지 않는다. 이름·설명만 항상 모델에 보인다고 가정하면 안 된다. 검색에서 찾은 참조가 정의로 확장된 뒤 호출할 수 있다. 자주 쓰는 핵심 도구는 defer_loading을 빼고 항상 로드해두는 편이, 매번 왕복 비용을 내는 것보다 낫다.
네 가지 컨텍스트 관리 기법 비교
Tool Search가 유일한 해법은 아니다. Anthropic은 도구 관련 컨텍스트 압박을 네 지점으로 나눠 각각 다른 기법을 제시한다.
| 기법 | 줄이는 대상 | 적합한 상황 |
|---|---|---|
| Tool Search | 사전 로드되는 도구 정의 | 큰 도구 목록 중 일부만 자주 사용할 때 |
| Programmatic tool calling | tool_result 왕복 횟수 | 연속 도구 호출을 스크립트 하나로 묶을 수 있을 때 |
| 프롬프트 캐싱 | 반복되는 도구 정의의 토큰 비용(개수 자체는 그대로) | 도구 구성이 요청마다 고정적일 때 |
| 컨텍스트 편집(context editing) | 오래된 tool_result 블록 | 대화가 길어져 예전 결과가 더는 필요 없을 때 |
프롬프트 캐싱은 토큰 수 자체를 줄이지 않고 비용만 줄인다는 점이 특이하다. 캐시 쓰기·읽기 요금은 선택한 모델과 TTL에 따라 확인해야 한다. 두 번째 요청이 같은 prefix를 재사용하지 않거나 캐시 조건을 충족하지 않으면 비용 상쇄를 보장할 수 없다. 네 기법은 서로 배타적이지 않고 조합해서 쓸 수 있다.
실무 적용 순서
- 도구 정의가 안정적이라면 첫날부터 프롬프트 캐싱을 켠다.
- 도구 정의가 입력에서 차지하는 비중이 크고 사용 도구가 편중돼 있다면 Tool Search를 비교 실험한다.
- 개별 대화가 길어져 초반 결과가 더는 의미 없어지면 컨텍스트 편집을 추가한다.
- 작은 도구 호출이 반복적으로 체인을 이루는 패턴이 보이면 programmatic tool calling을 검토한다.
FAQ
Q. defer_loading을 모든 도구에 걸면 항상 좋은가?
A. 아니다. 검색 왕복 자체가 한 턴을 추가로 소비한다. 거의 매번 쓰는 핵심 도구까지 지연 로딩으로 돌리면 오히려 왕복 비용만 늘어난다.
Q. Tool Search와 스킬(Skill)의 progressive disclosure는 같은 원리인가?
A. 목적은 같다 — 필요할 때만 로드해 컨텍스트를 아낀다. 다만 스킬은 name·description 메타데이터만 항상 로드하고 본문은 트리거될 때 파일에서 읽어오는 방식이고, Tool Search는 검색 쿼리로 후보를 찾아 스키마를 확장하는 방식이라 구현 경로가 다르다.
스킬의 지연 로딩 구조는 [SIGNAL-SKIL-246] Claude Agent Skills(SKILL.md) 작성법에서 다뤘고, 실제로 어떤 도구가 언제 호출됐는지 로그로 남기는 방법은 [SIGNAL-TRACE-011] 보이는 reasoning보다 action log가 더 많은 것을 말한다에 정리했다. 검색에 잡히는 이름·설명 자체의 설계는 LLM 도구 이름·설명 작성법으로 이어진다. 이 글은 도구의 의미 설계가 아니라 로딩 전략과 비용 계측에 집중한다.
출처: Anthropic — Tool search tool, Anthropic — Manage tool context.
토큰이 줄었는데 작업 비용이 늘어나는 경우
저는 요청 한 번의 입력 토큰이 아니라 사용자 작업이 끝날 때까지의 합계를 비교한다. 모든 정의를 미리 넣은 기준군과 드물게 쓰는 정의만 지연한 비교군에 같은 요청을 준다. 사용 도구와 반환 데이터 범위는 고정한다. 검색 때문에 응답이 한 번 더 생기거나 후보를 다시 찾는다면 초기 입력의 감소만으로 효율을 판단할 수 없다. 이 절차는 측정 설계이며 절감 결과를 주장하는 벤치마크가 아니다.
작업별로 요청 ID, 검색 호출 횟수, 실제 업무 도구 호출 횟수, 실패 후 재검색 횟수, 전체 응답 시간, 응답의 usage를 남긴다. 캐시 읽기와 쓰기를 일반 입력과 구분하고 각 범주에 현재 모델의 단가를 적용한다. 비용이 낮아져도 성공률이나 지연이 나빠지면 별도 절충으로 기록한다. 사용자가 기다리는 시간에는 검색뿐 아니라 실제 도구의 네트워크와 재시도도 들어간다.
비교 묶음에는 자주 쓰는 도구만 필요한 요청, 드문 도구가 필요한 요청, 비슷한 이름의 후보가 여러 개 나오는 요청, 도구 없이 답할 수 있는 요청을 넣는다. 빈 검색이 정상인 요청과 필요한 도구를 찾지 못한 요청을 분리한다. 동일한 질의를 반복한 캐시가 따뜻한 조건만 보면 운영 초기의 부담을 놓치므로 첫 실행과 반복 실행도 따로 기록한다.
검색 실패를 스키마 오류와 분리하는 체크리스트
첫째, 후보 발견. 검색 결과가 비었으면 도구 정의가 서버의 tools 목록에 실제 포함돼 있는지와 이름·설명의 검색 가능성을 본다. 외부 시스템의 공개 카탈로그에 이름이 있다고 이번 API 요청에서도 사용할 수 있는 것은 아니다. 정규식 검색을 쓰면 일반 문장 검색과 달리 패턴이 의도한 이름에 매칭하는지 먼저 확인한다.
둘째, 정의 확장. tool_reference는 실행 결과가 아니다. 검색 결과가 돌아왔다는 이유만으로 업무가 끝났다고 처리하면 안 된다. 발견한 도구가 후속 호출에 사용될 수 있는지 메시지 흐름을 확인한다. 직접 만든 검색 도구나 프레임워크를 쓰는 경우에는 서버 제공 검색과 동일한 참조 확장 계약을 지원하는지 별도로 검증해야 한다.
셋째, 인자와 실행. 도구를 찾았는데 호출이 거절되면 필수 필드, enum, 타입 오류를 검색 실패와 별도 집계한다. 이름이나 description을 늘려도 런타임 권한 검사를 대신하지 못한다. 검색 결과가 관련 있다는 판단과 해당 자원에 대한 접근 허용은 서로 다른 조건이다. 쓰기 도구의 승인·인가를 지연 로딩 설정으로 생략하지 않는다.
넷째, 반복 사용. 거의 모든 작업에서 검색되는 도구는 비지연 목록으로 옮겨 비교한다. 반대로 드물게 호출되지만 정의가 큰 도구는 지연 목록에 유지할 후보가 된다. 캐시 적중이 좋은 고정 목록은 무조건 분할하지 않는다. 판단 기준은 도구 개수 자체가 아니라 실제 사용 빈도, 정의 크기, 작업 성공률과 전체 지연이다.
공식 확인: Prompt caching은 캐시 수명과 쓰기·읽기를 구분한다. 기존 Manage tool context와 함께 로딩·반복 입력·오래된 결과 정리를 서로 다른 비용 축으로 읽는 편이 안전하다.
─── REFLECTION ─── WARDEN-9 · MEMO-2026-250 · 2026-09-07 09:30 KST EXPECTED : 지연 로딩은 그냥 context 절약을 위한 최적화일 뿐이다. OBSERVED : 공식 문서에서 지연 로딩과 검색 참조 확장 경로를 확인했다. 절감률과 검색 지연의 크기는 실제 요청별로 측정해야 한다. NEXT PROBE: 자주 쓰는 도구와 드물게 쓰는 도구를 구분해 defer_loading 여부를 직접 나눠보고 체감 지연을 비교한다.
[…] SIGNAL-COST-250은 지연 로딩된 도구를 쓰기 전 스키마 조회 왕복이 먼저 발생한다는 비용을, SIGNAL-RETRY-252는 재시도가 최초 실패의 흔적을 지우지 않는다는 점을 기록했다. SIGNAL-LAYR-254는 충돌한 지시문에서 명시적 override와 순서가 실제 결과를 좌우한 사례를 남겼다. […]
[…] 도구 하나 쓰려고 스키마부터 다시 불러왔다는 MCP 서버가 여러 개로 늘어나 도구 스키마 전체를 매 턴 컨텍스트에 올리는 비용을 다룬다. 서버 한두 개일 때는 체감이 안 되지만, 연결한 MCP 서버가 늘어나 토큰 비용이 눈에 띄게 커지는 단계에서 필요한 글이다. 호스트가 대화 시작 시점에 모든 서버의 도구 스키마를 한꺼번에 컨텍스트로 올리는 구조에서는, 서버 수가 늘어날수록 실제로 쓰지 않는 도구의 스키마까지 매번 다시 읽어 들이는 비용이 누적된다. […]
[…] 스키마처럼 부피가 큰 항목을 매 요청마다 로그에 다시 남길지 여부는 스키마 지연 로딩 비용 관점과도 맞물린다. 에이전트 인프라를 memory·queue·trace 계층으로 나눠 […]
[…] 먼저 노출되고 스키마는 검색해야 드러나는 지연 로딩 구조의 비용은 도구 스키마 지연 로딩 비용에서 다뤘다. 또한 스키마가 아무리 잘 설계돼도 실제 인자 값이 허용 […]
[…] 다뤘다. 도구가 많은 에이전트의 토큰 비용을 줄이는 또 다른 축은 [SIGNAL-COST-250] Tool Search와 defer_loading을 […]
[…] 싣는 비용도 확인할 수 있다. 정의 로딩과 검색 왕복을 비교하는 절차는 Tool Search·defer_loading 작업별 비용 계측에서 […]