Deferred Tools & ToolSearch

What You’ll Learn

In Session 5 you saw the two-layer trick that makes skills scale: names and one-line descriptions live in the system prompt, full definitions load only when a skill is invoked. The Fable 5 era generalizes that same idea to tools themselves. Not every tool schema is loaded into context up front anymore — many tools start out as names only, and a dedicated ToolSearch tool fetches their full schemas on demand.

By the end, you’ll understand:

• What a deferred tool is and how it appears in a session
• The three ToolSearch query forms: select:, keyword search, and +require
• The load-then-call flow — why a deferred tool can’t be called until its schema is fetched
• Why this design exists (spoiler: context is a budget)
• What it changes for MCP at scale, including subagents and workflow agents
• The one caveat that bites automation: interactively-authenticated MCP servers in headless runs

The Problem

For the model to call a tool, the tool’s full parameter schema — every field, type, constraint, and description — has to be in context. For a handful of built-in tools, that’s fine. But a real session’s tool surface doesn’t stay small:

• Built-in tools for files, shell, search, tasks, artifacts, scheduling
• Every MCP server you connect, each contributing its own set of tools
• All of it multiplied across every subagent, because each spawned agent gets its own context window

Here’s the painful part: in the old model, you paid for all of those schemas on every turn, whether or not a single one of those tools was ever called. Connect a large MCP server to look up one ticket, and its entire tool catalog rides along in context for the rest of the session — and in every subagent you spawn.

This is exactly the problem skills solved in Session 5, resurfacing one layer down. Skill definitions were deferred; tool schemas were not. The fix is the same shape.

How It Works

Deferred Tools: Names Without Schemas

In current builds, not every tool schema is loaded into context up front. Deferred tools appear by name only, listed inside <system-reminder> blocks (the same harness-injected notes you’ve seen carrying recalled memories and mode changes). Their parameter schemas are absent — which means they cannot be called yet. The model knows the tool exists; it doesn’t yet know how to invoke it.

                    Context window
┌────────────────────────────────────────────────────┐
│ Loaded tools — full schemas, callable now           │
│   • Read   (full JSON schema)                       │
│   • Edit   (full JSON schema)                       │
│   • Bash   (full JSON schema)                       │
├────────────────────────────────────────────────────┤
│ Deferred tools — names only, NOT callable yet       │
│   <system-reminder>                                 │
│     The following deferred tools are available      │
│     via ToolSearch: ...                             │
│     (schemas not loaded)                            │
│   </system-reminder>                                │
└────────────────────────────────────────────────────┘

Compare this to the skills diagram from Session 5 — it’s the same two-layer architecture. Layer 1 is a cheap index (names). Layer 2 is the expensive payload (full schemas), loaded on demand.

ToolSearch: Three Query Forms

ToolSearch is the bridge between the layers. It takes a query, matches it against the deferred tool list, and returns the full schema definitions for the matches. Three query forms:

Query	Form	What it does
"select:Read,Edit,Grep"	Exact selection	Fetches these exact tools by name
"notebook jupyter"	Keyword search	Matches keywords against the deferred list, returns the best matches
"+slack send"	Require + rank	Requires slack in the tool name, ranks results by the remaining terms

Use select: when you already know the tool’s name (the system-reminder told you). Use keyword search when you know what you want to do but not what the tool is called. Use +require when you know which server or family the tool belongs to and want to narrow within it.

Load, Then Call

Once ToolSearch returns a tool’s schema, that tool is callable exactly like any tool that was loaded from the start. The flow is always the same two steps:

 Deferred tool (name only)
        │
        │  ToolSearch("select:<name>")
        ▼
 Schema now in context
        │
        │  normal tool call
        ▼
 Tool executes

There’s no third state and no special calling convention. Deferral is invisible after the fetch.

Why This Exists: The Context Budget

Every token spent on an unused tool schema is a token not available for your code, your conversation, or your agents’ reasoning. The deferred-loading philosophy that skills pioneered — names and descriptions upfront, full definitions on demand — turns a fixed tax into a pay-per-use cost. You pay for Grep’s schema when you’re about to grep, not on every turn of a session that never searches anything.

MCP at Scale

This matters most for MCP. MCP servers are where tool surfaces get genuinely large, and deferral changes the economics in two ways:

1. Big servers stop taxing every turn. A session-connected MCP server’s tools sit in the deferred list as names. Large MCP tool surfaces no longer bloat every context window — you load the two tools you actually need, not the whole catalog.

2. Subagents and workflow agents load schemas per agent, on demand. Workflow and subagent contexts can reach all session-connected MCP tools via ToolSearch, with schemas loaded individually in whichever agent needs them. A fan-out of ten agents doesn’t mean ten copies of every MCP schema — it means each agent fetches only what its own task requires.

One caveat worth designing around: interactively-authenticated MCP servers — for example, claude.ai connectors — may be absent in headless or cron runs. A tool that’s available in your interactive session because you clicked through an auth flow may simply not exist when the same prompt runs on a schedule. If your automation depends on such a server, verify its presence rather than assuming it.

Hands-On Example

Let’s walk the full cycle: discover a deferred tool, load it, call it.

Step 1 — The session tells you what’s deferred. Early in a session, a system-reminder lists deferred tool names:

<system-reminder>
The following deferred tools are available via ToolSearch.
Their schemas are NOT loaded — use ToolSearch to load tool
schemas before calling them:
  Grep, ... (names only)
</system-reminder>

At this point Grep is visible but not callable — there’s no schema in context to build a valid call against.

Step 2 — Load it by exact name. Since the reminder gave you the name, use the select: form:

ToolSearch("select:Grep")

You can batch several at once — "select:Read,Edit,Grep" fetches all three in one call. Loading tools together is cheaper than three round-trips when you know you’ll need them.

Step 3 — Call it normally. ToolSearch returned the full schema, so the tool now behaves like any always-loaded tool. Claude calls Grep with regular parameters, gets regular results. Done.

The discovery variant. Suppose you don’t know the tool’s name — you just know you need to work with a Jupyter notebook. Keyword search does the matching for you:

ToolSearch("notebook jupyter")

The best-matching deferred tools come back with full schemas. And if you know the tool lives on your Slack MCP server but can’t remember the exact name:

ToolSearch("+slack send")

This requires slack in the tool name and ranks candidates by send — narrowing to one server’s tools instead of matching noise across the whole deferred list.

In practice you rarely trigger any of this by hand. Claude does the ToolSearch step itself when it decides a deferred tool is the right one for the job. But knowing the mechanism explains session behavior that otherwise looks odd — like a one-turn pause to “look up” a tool before using it, or an MCP tool that works interactively but vanishes in a cron run.

What Changed

Before (all schemas upfront)	After (deferred + ToolSearch)
Every tool schema in every context window	Names upfront; schemas fetched on demand
Connecting a big MCP server taxed every turn	Unused MCP tools cost nearly nothing until loaded
Each subagent carried the full tool surface	Each agent loads only the schemas its task needs
Tool surface growth degraded every session	Tool surface scales without a per-turn tax
Skills deferred, tools always eager	One deferred-loading philosophy for both layers

Key Insight

Context is a budget, and tools became pay-per-use.

The deeper pattern is worth naming, because you’ve now seen it three times in this course. Skills load names upfront and bodies on demand (Session 5). Memory loads an index (MEMORY.md) upfront and individual memory files on demand (Session 29). And now tools load names upfront and schemas on demand. The architecture keeps making the same bet: a cheap index in every context window, expensive payloads fetched only at the moment of use.

That bet is what lets the ecosystem grow without degrading. You can connect more MCP servers, install more skills, and accumulate more memory without each addition slowing down or crowding out every future session. The marginal cost of having a capability approaches zero; you pay only when you use it.

When you design your own MCP servers or agent setups, inherit the principle: make the index cheap and descriptive (good tool names and clear one-line descriptions make your tools easy to find and pick), and don’t worry about catalog size the way you used to.

Next Session

Session 31 covers Scheduled Autonomy: Loops, Wakeups & Cron — how Claude Code runs without you in the loop: /loop and its dynamic self-pacing mode, the ScheduleWakeup tool and its prompt-cache economics, cron jobs versus one-shot wakeups, and why an agent that knows when to sleep is cheaper than one that never does.