From bfbab44756aa1bb00c7f5773ca63bec9d881d762 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sat, 20 Dec 2025 13:46:24 +0800
Subject: [PATCH] docs: Improve MCP tool descriptions for clarity and
 completeness
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- smart_search: Condense verbose description from 40 to 12 lines while preserving key usage examples
- write_file: Add missing createDirectories parameter documentation
- edit_file: Clarify update/line mode naming and add batch edit examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 ccw/src/tools/edit-file.ts    | 12 ++++++---
 ccw/src/tools/smart-search.ts | 47 ++++++++---------------------------
 ccw/src/tools/write-file.ts   |  2 +-
 3 files changed, 19 insertions(+), 42 deletions(-)

diff --git a/ccw/src/tools/edit-file.ts b/ccw/src/tools/edit-file.ts
index afbf5170..098219a3 100644
--- a/ccw/src/tools/edit-file.ts
+++ b/ccw/src/tools/edit-file.ts
@@ -415,13 +415,17 @@ function executeLineMode(content: string, params: Params): LineModeResult {
 // Tool schema for MCP
 export const schema: ToolSchema = {
   name: 'edit_file',
-  description: `Edit file by text replacement or line operations.
+  description: `Edit file using two modes: "update" for text replacement (default) and "line" for line-based operations.
 
-Usage:
+Usage (update mode):
   edit_file(path="f.js", oldText="old", newText="new")
-  edit_file(path="f.js", mode="line", operation="insert_after", line=10, text="new line")
+  edit_file(path="f.js", edits=[{oldText:"a",newText:"b"},{oldText:"c",newText:"d"}])
 
-Options: dryRun=true (preview diff), replaceAll=true (replace all occurrences)`,
+Usage (line mode):
+  edit_file(path="f.js", mode="line", operation="insert_after", line=10, text="new line")
+  edit_file(path="f.js", mode="line", operation="delete", line=5, end_line=8)
+
+Options: dryRun=true (preview diff), replaceAll=true (update mode only)`,
   inputSchema: {
     type: 'object',
     properties: {
diff --git a/ccw/src/tools/smart-search.ts b/ccw/src/tools/smart-search.ts
index 7736c920..443e390f 100644
--- a/ccw/src/tools/smart-search.ts
+++ b/ccw/src/tools/smart-search.ts
@@ -946,46 +946,19 @@ async function executePriorityFallbackMode(params: Params): Promise<SearchResult
 // Tool schema for MCP
 export const schema: ToolSchema = {
   name: 'smart_search',
-  description: `Intelligent code search with five modes: auto, hybrid, exact, ripgrep, priority.
+  description: `Intelligent code search with five modes. Use "auto" mode (default) for intelligent routing.
 
-**Quick Start:**
-  smart_search(query="authentication logic")           # Auto mode (intelligent routing)
-  smart_search(action="init", path=".")                # Initialize index (required for hybrid)
-  smart_search(action="status")                        # Check index status
+**Usage:**
+  smart_search(query="authentication logic")        # auto mode - routes to best backend
+  smart_search(query="MyClass", mode="exact")       # exact mode - precise FTS matching
+  smart_search(query="auth", mode="ripgrep")        # ripgrep mode - fast literal search (no index)
+  smart_search(query="how to auth", mode="hybrid")  # hybrid mode - semantic search (requires index)
 
-**Five Modes:**
-  1. auto (default): Intelligent routing based on query and index
-     - Natural language + index → hybrid
-     - Simple query + index → exact
-     - No index → ripgrep
+**Index Management:**
+  smart_search(action="init")                       # Create FTS index for current directory
+  smart_search(action="status")                     # Check index and embedding status
 
-  2. hybrid: CodexLens RRF fusion (exact + fuzzy + vector)
-     - Best quality, semantic understanding
-     - Requires index with embeddings
-
-  3. exact: CodexLens FTS (full-text search)
-     - Precise keyword matching
-     - Requires index
-
-  4. ripgrep: Direct ripgrep execution
-     - Fast, no index required
-     - Literal string matching
-
-  5. priority: Fallback strategy for best balance of speed and recall
-     - Tries searches in order: hybrid -> exact -> ripgrep
-     - Returns results from the first successful search with results
-     - More efficient than running all backends in parallel
-
-**Actions:**
-  - search (default): Intelligent search with auto routing
-  - init: Create CodexLens index
-  - status: Check index and embedding availability
-  - search_files: Return file paths only
-
-**Workflow:**
-  1. Run action="init" to create index
-  2. Use auto mode - it routes to hybrid for NL queries, exact for simple queries
-  3. Use priority mode for comprehensive fallback search`,
+**Modes:** auto (intelligent routing), hybrid (semantic, needs index), exact (FTS), ripgrep (fast, no index), priority (fallback: hybrid→exact→ripgrep)`,
   inputSchema: {
     type: 'object',
     properties: {
diff --git a/ccw/src/tools/write-file.ts b/ccw/src/tools/write-file.ts
index f74a2bfe..5420db2c 100644
--- a/ccw/src/tools/write-file.ts
+++ b/ccw/src/tools/write-file.ts
@@ -105,7 +105,7 @@ export const schema: ToolSchema = {
   description: `Write content to file. Auto-creates parent directories.
 
 Usage: write_file(path="file.js", content="code here")
-Options: backup=true (backup before overwrite), encoding="utf8"`,
+Options: backup=true (backup before overwrite), createDirectories=false (disable auto-creation), encoding="utf8"`,
   inputSchema: {
     type: 'object',
     properties: {