[BUG] Deferred tools waste ~20k tokens per session when disabled

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug: Deferred Tools Consume Tokens Even When Tools Are Disabled

Summary

Deferred tool definitions (MCP tools and system tools) are included in every conversation's system context regardless of whether tools are enabled or disabled in settings. This wastes ~20k tokens per conversation when tools are explicitly disabled.

Problem Statement

Users who disable tools and MCP to save tokens are charged for deferred tool listings anyway. Even with permissionMode=default (no tools enabled), ~20.1k tokens are consumed by deferred tools that cannot be used.

Expected Behavior

• When tools/MCP are disabled, deferred tool listings should NOT appear in the system context
• Token cost should be zero or minimal when tools are disabled
• Users who explicitly request "don't load tools to save tokens" should not be charged for tools

Actual Behavior

Tokens consumed by deferred tools across all settings states:

| State | MCP Tools (deferred) | System Tools (deferred) | Total |
|-------|---------------------|------------------------|-------|
| Tools disabled | 4.6k | 15.5k | 20.1k |
| Tools enabled (permissionMode=auto) | 6.2k | 16.1k | 22.3k |

Even with tools disabled, 20.1k tokens are wasted every conversation.
Enabling tools adds only 2.2k additional tokens, suggesting the system includes deferred tool listings regardless of settings.

Reproduction Steps

1. Create a project with tools disabled:

``json
{
"permissions": {
"defaultMode": "default" // or omit entirely
}
}
``
(Or use default global settings with no tool permissions)

1. Start a new Claude Code session

1. Run /context to check token usage

1. Observe "MCP tools (deferred)" and "System tools (deferred)" consuming ~20k tokens despite tools being unavailable

Impact

• 20.1k tokens wasted per conversation when users explicitly disable tools for token savings
• Users cannot opt out of deferred tool costs
• Amplified for users running many short conversations (e.g., automated loops, batch processing)
• Conflicts with documented behavior: The feedback memory "Defer tool loading" says "Don't pre-load deferred tool schemas at start; only fetch via ToolSearch when needed to save ~22.3k tokens" — yet this is not happening

Root Cause Analysis

The system automatically includes deferred tool listings in the system context regardless of:

• Whether permissionMode is set to restrict/disable tools
• Whether the user has explicitly asked not to load tools
• Whether any tools will ever be callable in that session

Deferred tools should only be included when:

1. Tools are actually enabled (permissionMode=auto or similar), OR
2. The user explicitly requests them via ToolSearch

Suggested Fix

Option A (Strict): Omit deferred tool listings entirely when permissionMode disables tools
Option B (Flexible): Add a disableDeferredTools setting to opt out of deferred tool token cost

Environment

• OS: Windows 11 Home 10.0.26200
• Claude Code: Haiku 4.5
• Settings: Project-level .claude/settings.json with permissionMode=auto for testing; global defaults used for "disabled" state
• Session date: 2026-08-02

Related Memory

• Linked to feedback memory: [[Defer tool loading]] — user requested this optimization but it's not working as documented

What Should Happen?

Expected Behavior: Deferred Tools Token Cost

What Should Happen

When Tools Are Disabled

When permissionMode is set to default, plan, or any restrictive mode that disables tool use:

• Deferred tool listings should NOT appear in system context
• Token cost should be ~0 for deferred tools
• MCP tool definitions should not be loaded or indexed
• System tool schemas should not be included

Expected /context output:

MCP tools (deferred):          0 tokens (0%)  ← Omitted entirely
System tools (deferred):       0 tokens (0%)  ← Omitted entirely

When Tools Are Enabled

When permissionMode=auto or similar permissive setting:

• Deferred tool listings MAY be included (indexed, not full schemas)
• Token cost should be minimal (~2-3k for index only)
• Full schemas load on-demand only when tool is actually called

Expected /context output:

MCP tools (deferred):      2-3k tokens (1-2%)  ← Index only, minimal
System tools (deferred):   2-3k tokens (1-2%)  ← Index only, minimal

When User Explicitly Requests No Deferred Tools

When memory or settings explicitly request "don't load tools/MCP to save tokens":

• System should honor this request
• No tool-related tokens should be charged
• No tool listings in context, even if tools are technically "enabled"

Rationale

1. Users should not pay for features they disable. Tokens are a limited, billable resource.

1. The documented behavior promises this. The feedback memory "Defer tool loading" states: "Don't pre-load deferred tool schemas at start; only fetch via ToolSearch when needed to save ~22.3k tokens." This only works if deferred tools are omitted when disabled.

1. It's technically feasible. The system already distinguishes between:

• Enabled vs disabled tools (via permissionMode)
• Loaded vs deferred tools (some are already deferred)
• So conditional inclusion is architecturally sound

1. It aligns with MCP's own defer_loading. The MCP protocol already has this pattern—servers mark tools as deferred, and the server only sends full schemas on-demand. Claude Code should do the same for its own tools.

Minimum Acceptable Behavior

At minimum, provide a setting to opt out:

{
  "disableDeferredTools": true
}

When set, deferred tool listings are completely omitted from system context, saving ~20k tokens per session for users who need the savings.

Current vs Expected Token Cost

| Scenario | Current Cost | Expected Cost | Savings |
|----------|--------------|---------------|---------|
| Tools disabled, user asks not to load | 20.1k tokens | 0 tokens | 20.1k ⚠️ |
| Tools enabled (auto mode) | 22.3k tokens | 2-3k tokens | 19.3k ⚠️ |
| Tools enabled + using tools actively | 22.3k tokens | ~2-3k (index) + schemas on-demand | ~20k potential |

User Impact: Wasting 20k tokens per conversation is equivalent to ~5-10% of context window on many plans.

Error Messages/Logs

Steps to Reproduce

Steps to Reproduce: Deferred Tools Token Waste

Environment Setup

Requirements:

• Claude Code CLI or VSCode extension
• Access to /context command
• Token counter visible (built-in to Claude Code)

---

Test Case 1: Tools Disabled (Default Settings)

Setup

1. Open a new directory or use an existing project without custom .claude/settings.json
2. Ensure ~/.claude/settings.json has no tool permissions configured (default state)
3. Verify no MCP servers are enabled globally

Steps

1. Start a new Claude Code session:

``bash
claude
``

1. At the prompt, type:

``
/context
``

1. Look at the output table under "Estimated usage by category"

1. Record the values:

• MCP tools (deferred): _____ tokens
• System tools (deferred): _____ tokens
• Total deferred: _____ tokens

Expected Result ✅

• MCP tools (deferred): 0 tokens
• System tools (deferred): 0 tokens
• Total: 0 tokens (tools are disabled, shouldn't be included)

Actual Result ❌

• MCP tools (deferred): ~4.6k tokens
• System tools (deferred): ~15.5k tokens
• Total: ~20.1k tokens wasted

---

Test Case 2: Tools Enabled (permissionMode=auto)

Setup

1. Create .claude/settings.json in project root with:

``json
{
"permissions": {
"defaultMode": "auto"
}
}
``

1. Start a new session:

``bash
claude
``

Steps

1. Type /context
2. Record the values:

• MCP tools (deferred): _____ tokens
• System tools (deferred): _____ tokens
• Total deferred: _____ tokens

Expected Result ✅

• MCP tools (deferred): ~2-3k tokens (index only, minimal)
• System tools (deferred): ~2-3k tokens (index only, minimal)
• Total: ~4-6k tokens (reasonable for enabled tools)

Actual Result ❌

• MCP tools (deferred): ~6.2k tokens
• System tools (deferred): ~16.1k tokens
• Total: ~22.3k tokens (significantly more than disabled case)

---

Test Case 3: Compare the Delta

Calculation

Cost to enable tools = (22.3k) - (20.1k) = ~2.2k tokens

Problem: Tools add only 2.2k tokens, yet:
- Disabled case: 20.1k tokens (shouldn't be there)
- Enabled case: 22.3k tokens (index + schemas)

This proves ~20k tokens are wasted when tools are disabled.

---

Verification Checklist

• [ ] Test Case 1 shows ~20k wasted tokens with tools disabled
• [ ] Test Case 2 shows ~22k tokens with tools enabled
• [ ] The delta (2.2k) is the actual cost to enable tools
• [ ] Deferred tool listings appear in both cases despite disabled state in Test 1
• [ ] /context clearly labels them as "deferred" (not loaded, but still included)

---

Screenshot/Output Template

Scenario: [Tools Disabled / Tools Enabled]
Date: YYYY-MM-DD
Model: [Your model]

### /context Output
| Category | Tokens | Percentage |
|----------|--------|------------|
| MCP tools (deferred) | X,XXXk | X.X% |
| System tools (deferred) | XX,XXXk | XX.X% |
| ... (other rows) |

### Findings
- Tools state: [disabled/enabled]
- Total deferred tokens: X,XXXk
- Expected tokens: X,XXXk
- Wasted tokens: X,XXXk

---

Notes for Reproducers

1. Token count varies slightly by model/version — differences of 100-500 tokens are noise. Focus on the order of magnitude (4-6k vs 20k+).

1. MCP servers — If you have custom MCP servers registered, they'll inflate the "MCP tools" count. The "System tools" waste (~15-16k) is the most reliable indicator.

1. Cache effects — Running /context multiple times in the same session may show cached results. Start fresh sessions for clean measurements.

1. Clear between tests:

``bash
# Removes session state between test cases
/clear
``
Then start a new session for the next test case.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.219

Platform

Other

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_