Claude Code Lazy-Loads Tool Schemas via ToolSearch to Save Tokens

A Reddit analysis of Claude Code's system prompt reveals that tools are lazy-loaded to reduce token consumption. Instead of sending every tool's full schema with every request, Claude Code sends a list of tool names in a <system-reminder> tag and instructs the model to call ToolSearch first to load the schema for each tool.

How It Works

The system prompt includes an instruction like this:

<system-reminder>
The following deferred tools are now available via ToolSearch. Their schemas are NOT loaded — calling them directly will fail with InputValidationError. Use ToolSearch with query "select:<name>[,<name>...]" to load tool schemas before calling them:

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

The <system-reminder> is injected only in the first user message of the conversation. A similar block lists skills with single-line descriptions.

Token Impact

According to the post, the system instructions plus reminders alone consumed 38k tokens on a simple "hi" test message. Loading every tool's full schema upfront would drastically increase that burn — hence the lazy-loading approach.

Practical Implications

If you're building on Claude Code or similar agent-based systems, this pattern is worth adopting:

• Defer schemas for rarely-used tools until needed.
• Use a ToolSearch-like command to explicitly request schemas.
• Keep reminders within the first message to avoid repeating context.

This also means that if you're writing custom tools for Claude Code, you must ensure the model can discover them via ToolSearch — otherwise they'll be invisible or cause validation errors.