Claude Code가 ToolSearch를 통해 도구 스키마를 지연 로딩하여 토큰을 절약합니다

Claude Code의 시스템 프롬프트에 대한 Reddit 분석에 따르면, 도구는 토큰 소모를 줄이기 위해 지연 로딩됩니다. 모든 요청에 모든 도구의 전체 스키마를 보내는 대신, Claude Code는 <system-reminder> 태그에 도구 이름 목록을 보내고, 모델이 먼저 ToolSearch를 호출하여 각 도구의 스키마를 로드하도록 지시합니다.

작동 방식

시스템 프롬프트에는 다음과 같은 지침이 포함됩니다:

<system-reminder>
다음 지연 도구는 이제 ToolSearch를 통해 사용할 수 있습니다. 해당 스키마는 로드되지 않았습니다. 직접 호출하면 InputValidationError가 발생합니다. 도구를 호출하기 전에 ToolSearch에 쿼리 "select:<name>[,<name>...]"를 사용하여 도구 스키마를 로드하세요:

AskUserQuestion CronCreate CronDelete CronList EnterPlanMode EnterWorktree ExitPlanMode ExitWorktree Monitor NotebookEdit PushNotification RemoteTrigger TaskOutput TaskStop TodoWrite WebFetch WebSearch
[+ ~130 MCP 도구 (Slack, Notion, Gmail...)]
</system-reminder>

<system-reminder>는 대화의 첫 번째 사용자 메시지에만 삽입됩니다. 유사한 블록이 한 줄 설명과 함께 스킬을 나열합니다.

토큰 영향

게시물에 따르면, 시스템 지침과 알림만으로도 간단한 "hi" 테스트 메시지에서 38k 토큰을 소비했습니다. 모든 도구의 전체 스키마를 처음에 로드하면 그 소모량이 급격히 증가하므로, 지연 로딩 방식을 채택한 것입니다.

실용적 의미

Claude Code나 유사한 에이전트 기반 시스템을 구축 중이라면, 이 패턴을 채택할 가치가 있습니다:

• 드물게 사용되는 도구의 스키마는 필요할 때까지 지연하세요.
• ToolSearch와 유사한 명령을 사용하여 스키마를 명시적으로 요청하세요.
• 알림은 첫 번째 메시지 내에 유지하여 컨텍스트 반복을 피하세요.

또한, Claude Code용 맞춤 도구를 작성하는 경우 모델이 ToolSearch를 통해 이를 발견할 수 있도록 해야 합니다. 그렇지 않으면 보이지 않거나 유효성 검사 오류가 발생합니다.