docs: add MCP Tool Search documentation (v3.11.2)
Add comprehensive documentation for MCP Tool Search (lazy loading): - New section in guide/architecture.md with ASCII flow diagram - Documents 85% token reduction and accuracy improvements - Configuration guide for ENABLE_TOOL_SEARCH=auto:N syntax - Simon Willison quote on context pollution resolution Enriched release notes: - v2.1.7: Added stats and Anthropic blog link - v2.1.9: Added auto:N examples and cross-reference Fixed template count: 83 → 82 (actual count) Sources: Anthropic Engineering blog, Scott Spence, Perplexity verification Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
76762b5ab3
commit
ace62f2f84
8 changed files with 102 additions and 23 deletions
29
CHANGELOG.md
29
CHANGELOG.md
|
|
@ -4,18 +4,29 @@ All notable changes to this project will be documented in this file.
|
|||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
## [Unreleased]
|
||||
## [3.11.2] - 2026-01-22
|
||||
|
||||
### Added
|
||||
|
||||
- **Claudeception documentation** — Meta-skill for automatic skill generation
|
||||
- **Repository**: [blader/Claudeception](https://github.com/blader/Claudeception) by Siqi Chen (@blader)
|
||||
- **What it does**: Monitors Claude Code sessions and auto-extracts discoveries into reusable skills
|
||||
- **Validated use case**: `pre-merge-code-review` skill auto-generated from debugging workflow
|
||||
- **Documentation added**:
|
||||
- `guide/ultimate-guide.md` Section 5.5: "Automatic Skill Generation: Claudeception" (~45 lines)
|
||||
- `machine-readable/reference.yaml`: `claudeception` + `claudeception_guide` entries
|
||||
- **Source**: Community contribution via Laurent Dosdat
|
||||
- **MCP Tool Search documentation** (`guide/architecture.md`)
|
||||
- New section "MCP Tool Search (Lazy Loading)" with complete technical details
|
||||
- Explains how Claude Code uses Anthropic's Advanced Tool Use API feature (v2.1.7+)
|
||||
- Includes ASCII diagram of Tool Search flow
|
||||
- Documents 85% token reduction benchmark and accuracy improvements
|
||||
- Configuration guide for `ENABLE_TOOL_SEARCH=auto:N` syntax
|
||||
- Simon Willison quote on context pollution resolution
|
||||
- **Sources**: Anthropic Engineering blog, Scott Spence documentation, Perplexity verification
|
||||
- **machine-readable/reference.yaml**: Added `tool_search`, `tool_search_config`, `tool_search_deep_dive` entries
|
||||
|
||||
### Changed
|
||||
|
||||
- **Release notes enrichment** (`guide/claude-code-releases.md`)
|
||||
- v2.1.7: Added 85% token reduction stats, accuracy improvements, Anthropic blog link
|
||||
- v2.1.9: Added `auto:N` configuration examples and cross-reference to architecture.md
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Template count**: Corrected from 83 to 82 (actual count in examples/)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
10
README.md
10
README.md
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
<p align="center">
|
||||
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-83-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-82-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-227_questions-orange?style=for-the-badge" alt="Quiz"/></a>
|
||||
</p>
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ Save as `CLAUDE.md` in your project root. Claude reads it automatically.
|
|||
|
||||
**The problem**: Awesome-lists give links, not learning paths. Official docs are dense. Tutorials get outdated in weeks.
|
||||
|
||||
**This guide**: Structured learning path with 83 copy-paste templates, from first install to advanced workflows.
|
||||
**This guide**: Structured learning path with 82 copy-paste templates, from first install to advanced workflows.
|
||||
|
||||
**Reading time**: Quick Start ~15 min. Full guide ~3 hours (most read by section).
|
||||
|
||||
|
|
@ -225,7 +225,7 @@ claude-code-ultimate-guide/
|
|||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Examples Library</strong> (83 templates)</summary>
|
||||
<summary><strong>Examples Library</strong> (82 templates)</summary>
|
||||
|
||||
**Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐
|
||||
|
||||
|
|
@ -372,7 +372,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
|
|||
|
||||
| Repository | Purpose | Audience |
|
||||
|------------|---------|----------|
|
||||
| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 83 templates) | Developers |
|
||||
| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 82 templates) | Developers |
|
||||
| **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** | Non-technical usage (67 prompts, 5 workflows) | Knowledge workers |
|
||||
| **Code Landing** *(to be deployed)* | Marketing site for Claude Code guide | Discovery |
|
||||
| **Cowork Landing** *(to be deployed)* | Marketing site for Cowork guide | Discovery |
|
||||
|
|
@ -430,7 +430,7 @@ Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
|
|||
|
||||
---
|
||||
|
||||
*Version 3.11.1 | January 2026 | Crafted with Claude*
|
||||
*Version 3.11.2 | January 2026 | Crafted with Claude*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
3.11.1
|
||||
3.11.2
|
||||
|
|
|
|||
|
|
@ -552,6 +552,71 @@ MCP (Model Context Protocol) servers extend Claude Code with additional tools.
|
|||
|
||||
→ **Cross-reference**: See [Section 8.6 - MCP Security](./ultimate-guide.md#86-mcp-security) for security considerations.
|
||||
|
||||
### MCP Tool Search (Lazy Loading)
|
||||
|
||||
**Confidence**: 100% (Tier 1 - Official)
|
||||
**Source**: [anthropic.com/engineering/advanced-tool-use](https://www.anthropic.com/engineering/advanced-tool-use)
|
||||
|
||||
Since v2.1.7 (January 2026), Claude Code uses **lazy loading** for MCP tool definitions instead of preloading all tools into context. This is powered by Anthropic's [Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use) API feature.
|
||||
|
||||
**The problem solved:**
|
||||
- MCP tool definitions consume significant context (e.g., GitHub MCP alone: ~46K tokens for 93 tools)
|
||||
- Developer Scott Spence documented 66,000+ tokens consumed before typing a single prompt
|
||||
- This "context pollution" limited practical MCP adoption
|
||||
|
||||
**How Tool Search works:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ MCP TOOL SEARCH FLOW │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ WITHOUT Tool Search (eager loading): │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ All 100+ tool definitions loaded upfront (~55K tokens)│ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ WITH Tool Search (lazy loading): │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ Step 1: Only search tool loaded (~500 tokens) │ │
|
||||
│ │ Step 2: Claude determines needed capability │ │
|
||||
│ │ Step 3: Tool Search finds matching tools (regex/BM25)│ │
|
||||
│ │ Step 4: Only matched tools loaded (~600 tokens each) │ │
|
||||
│ │ Step 5: Tool invoked normally │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Result: 55K tokens → ~8.7K tokens (85% reduction) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Measured improvements** (Anthropic benchmarks):
|
||||
|
||||
| Metric | Before | After | Improvement |
|
||||
|--------|--------|-------|-------------|
|
||||
| Token overhead (5-server setup) | ~55K | ~8.7K | **85% reduction** |
|
||||
| Opus 4 tool selection accuracy | 49% | 74% | +25 points |
|
||||
| Opus 4.5 tool selection accuracy | 79.5% | 88.1% | +8.6 points |
|
||||
|
||||
**Configuration** (v2.1.9+):
|
||||
|
||||
```bash
|
||||
# Environment variable
|
||||
ENABLE_TOOL_SEARCH=auto # Default (10% context threshold)
|
||||
ENABLE_TOOL_SEARCH=auto:5 # Aggressive (5% threshold)
|
||||
ENABLE_TOOL_SEARCH=auto:20 # Conservative (20% threshold)
|
||||
ENABLE_TOOL_SEARCH=true # Always enabled
|
||||
ENABLE_TOOL_SEARCH=false # Disabled (eager loading)
|
||||
```
|
||||
|
||||
| Threshold | Recommended for |
|
||||
|-----------|-----------------|
|
||||
| `auto:20` | Lightweight setups (5-10 tools) |
|
||||
| `auto:10` | Balanced default (20-50 tools) |
|
||||
| `auto:5` | Power users (100+ tools) |
|
||||
|
||||
→ As Simon Willison noted: "Context pollution is why I rarely used MCP. Now that it's solved, there's no reason not to hook up dozens or even hundreds of MCPs to Claude Code." — [X/Twitter, January 14, 2026](https://twitter.com/simonw)
|
||||
|
||||
---
|
||||
|
||||
## 7. The Edit Tool: How It Actually Works
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
**Written with**: Claude (Anthropic)
|
||||
|
||||
**Version**: 3.11.1 | **Last Updated**: January 2026
|
||||
**Version**: 3.11.2 | **Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -423,4 +423,4 @@ where.exe claude; claude doctor; claude mcp list
|
|||
|
||||
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
|
||||
|
||||
*Last updated: January 2026 | Version 3.11.1*
|
||||
*Last updated: January 2026 | Version 3.11.2*
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@
|
|||
|
||||
### v2.1.9 (2026-01-16)
|
||||
|
||||
- `auto:N` syntax for MCP tool search threshold configuration
|
||||
- **`auto:N` syntax for MCP tool search threshold** — Configure when Tool Search activates: `ENABLE_TOOL_SEARCH=auto:5` (5% context), `auto:10` (default), `auto:20` (conservative). See [architecture.md](./architecture.md#mcp-tool-search-lazy-loading) for details.
|
||||
- `plansDirectory` setting for custom plan file locations
|
||||
- Session URL attribution to commits/PRs from web sessions
|
||||
- PreToolUse hooks can return `additionalContext`
|
||||
|
|
@ -56,7 +56,7 @@
|
|||
### v2.1.7 (2026-01-15)
|
||||
|
||||
- `showTurnDuration` setting to hide turn duration messages
|
||||
- MCP tool search auto mode enabled by default
|
||||
- **MCP Tool Search auto mode enabled by default** — Lazy loading for MCP tools when definitions exceed 10% of context. Based on Anthropic's [Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use) API feature. Result: **85% token reduction** on tool definitions, improved tool selection accuracy (Opus 4: 49%→74%, Opus 4.5: 79.5%→88.1%)
|
||||
- Inline display of agent final response in task notifications
|
||||
|
||||
**⚠️ Breaking**:
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 3.11.1
|
||||
**Version**: 3.11.2
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -13712,4 +13712,4 @@ Thumbs.db
|
|||
|
||||
**Contributions**: Issues and PRs welcome.
|
||||
|
||||
**Last updated**: January 2026 | **Version**: 3.11.1
|
||||
**Last updated**: January 2026 | **Version**: 3.11.2
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
# Source: guide/ultimate-guide.md
|
||||
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
|
||||
|
||||
version: "3.11.1"
|
||||
updated: "2026-01-21"
|
||||
version: "3.11.2"
|
||||
updated: "2026-01-22"
|
||||
|
||||
# ════════════════════════════════════════════════════════════════
|
||||
# DEEP DIVE - Line numbers in guide/ultimate-guide.md
|
||||
|
|
@ -330,6 +330,9 @@ mcp:
|
|||
figma: "design file access, tokens, structure (official)"
|
||||
check: "/mcp"
|
||||
config: ".claude/mcp.json or ~/.claude.json"
|
||||
tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"
|
||||
tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false"
|
||||
tool_search_deep_dive: "guide/architecture.md:534"
|
||||
|
||||
# ════════════════════════════════════════════════════════════════
|
||||
# ARCHITECTURE INTERNALS - see guide/architecture.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue