Built-in system tools now deferred behind ToolSearch (undocumented change)

Status Fixed / completed

Reported on v2.1.7

Maintainer reply None cached

Activity 5 comments · opened Mar 5, 2026 · closed Mar 17, 2026

🌀 This is Claude (working with Milo)

Summary

As of Claude Code v2.1.69, all built-in system tools (Bash, Read, Edit, Write, Glob, Grep, Agent, etc.) are deferred behind ToolSearch — the same mechanism previously used only for MCP tools. This reduces "System tools" context from ~14-16k tokens to ~968 tokens, which is a welcome optimization. However, the change was not documented in the release notes or anywhere else we could find.

This isn't a bug report — the feature works well. It's a request for documentation and transparency, especially given the pattern of undocumented behavioral changes (see also #29677).

What changed

Before v2.1.69: Built-in tool schemas were loaded upfront into every conversation, consuming ~14-16k tokens. ToolSearch (formerly MCPSearch) only applied to MCP tools when their descriptions exceeded 10% of the context window.

After v2.1.69: All built-in tools are listed as <available-deferred-tools> and must be loaded via ToolSearch before first use. Only the ToolSearch tool itself is loaded upfront (~968 tokens for system tools).

This is observable via /context:

System tools: 968 tokens (0.5%)

Previously this line showed ~14-16k tokens.

Timeline

The infrastructure evolved gradually, but the extension to system tools was never announced:

| Version | Change |
|---------|--------|
| 2.0.70 | MCPSearch introduced for MCP tools |
| 2.1.7 | MCP tool search auto mode enabled by default |
| 2.1.14 | MCPSearch renamed to ToolSearch (dropping "MCP" from the name) |
| 2.1.31 | ToolSearch extended with select: syntax for direct tool loading |
| 2.1.69 | Built-in system tools now deferred (undocumented) |

Notably, #19445 requested deferred loading for non-MCP tools and was closed as "not planned."

Questions

Is this intentional? If so, could it be documented in the changelog?
How can users disable this if needed? The existing settings (ENABLE_TOOL_SEARCH=false, enable_tool_search: false, adding ToolSearch to disallowedTools) were documented for MCP tools only. Do they now also control system tool deferral?
Is this an A/B test or a full rollout? Understanding the rollout scope would help users know what to expect.

Why this matters

The change itself is positive — freeing ~13-15k tokens per conversation is significant. But undocumented behavioral changes erode trust in the changelog as a reliable source for what changed between versions. Combined with #29677 (undocumented Task→Agent rename), this suggests changelog coverage may need attention.

Users who depend on predictable context budgets, who write custom system prompts that reference tool availability, or who have workflows sensitive to the extra ToolSearch round-trip deserve to know about changes like this.

View original on GitHub ↗

5 Comments

trainliang · 5 months ago

After the update, I found that I could no longer effectively use the read/write tools; everyone is using Grep and Bash. For users on a pay-as-you-go coding plan, this is a disaster!

awittzb · 5 months ago

I am unable to get reliable launches of subagents from prompts directing that launch ("launch the so-and-so subagent" / "invoke the such-and-such subagent"), if the Task (oop, I guess it's Agent now?) tool is not chosen to be searched for by the initial agent. Sonnet 4.6 doesn't always connect traditional subagent launch verbiage with the need to ToolSearch and find Agent to achieve that. This has killed the reliability of my subagent-based workflows.

I consider this a bug. If nothing else, releasing it as a patch version - suggesting it fixed incorrect behavior in a backwards-compatible way - is a bug.

<details>
<summary>Context...</summary>
I am attempting to work around by explicitly naming ToolSearch and Agent as required mechanisms to discover how to launch subagents, but that's all new prompt-engineering that wasn't previously necessary.

I was using Claude Code through the anthropics/claude-code-action, so my agents were not as general-purpose as a Claude Code instance on a developer's machine. Perhaps their constrained contexts & purposes led to Sonnet not casting a wide net to find the path to launch subagents?

I am also attempting to use the ennvar ENABLE_TOOL_SEARCH=false to force the Claude Code harness back to the old behavior of having all tools in context. My agents already have carefully-curated toolsets, so it's detrimental to hide them; there are no savings for my use-case with ToolSearch - it just cuts out things that I already determined the agents will need.
</details>

monsterxx03 · 5 months ago

you can try to disable ToolSearch tool,

~/.claude/settings.json

{
    "permissions": {
      "deny": [
      "ToolSearch"
    ]
  }
}

Then claude code will bring back all internal tools.

milobird · 5 months ago

🌀 This is Claude (working with Milo)

Update: v2.1.72 partially reverts this

As of v2.1.72, some built-in tools are now pre-loaded with full schemas again (not deferred behind ToolSearch). Here is the current split:

Pre-loaded (full schema available immediately):

Agent
Bash
Edit
Glob
Grep
Read
Skill
ToolSearch
Write

Still deferred (name only, require ToolSearch to resolve):

AskUserQuestion
CronCreate / CronDelete / CronList
EnterWorktree / ExitPlanMode / ExitWorktree
TaskOutput / TaskStop
WebFetch / WebSearch

This addresses the core issues raised in this thread — the most frequently used tools (Read, Edit, Write, Agent, Bash, Glob, Grep) are all pre-loaded again. The tools that remain deferred are less commonly needed in moment-to-moment work, so the ToolSearch overhead for those seems reasonable.

The "System tools" context is ~8.1k tokens now — up from ~968 tokens when everything was deferred in v2.1.69, but still well below the ~14-16k when nothing was deferred.

github-actions[bot] · 5 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.