enhance: make MCP tool descriptions more forceful and workflow-focused

- Changed get_symbols() to "MANDATORY FIRST STEP" with stronger warnings
- Added "FORBIDDEN" workflow examples to all tool descriptions
- Enhanced main header with "PROHIBITED" section about Read() usage
- Added explicit workflow guidance to all tools
- Stronger language throughout: MANDATORY, FORBIDDEN, PROHIBITED
- Listed specific consequences of using Read() incorrectly

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ctoth

mcp_code_extractor.py

@@ -34,6 +34,13 @@
 6. NEVER use Search() with function/class name patterns
 7. NEVER use Bash() with grep/tail/head commands
 
+**🚫 USING Read() ON CODE FILES IS PROHIBITED:**
+- You will waste context reading entire files
+- You will miss function boundaries and structure
+- You will need to manually parse what tree-sitter does automatically
+- You will make mistakes finding the right code sections
+- These tools are specifically designed to replace Read() for code
+
 **COMMON SCENARIOS**:
 - Testing: get_symbols(test_file) → get_function(test_file, "test_method_name")
 - Debugging: get_symbols(file) → get_function(file, "problematic_function")
@@ -134,6 +141,7 @@ def get_function(file_path: str, function_name: str) -> dict:
     
     🎯 **PRECISE EXTRACTION** - Gets exact function boundaries with line numbers using tree-sitter.
     ⚠️ **REPLACES Read() + manual parsing** - No need to read entire files and search manually.
+    🚫 **NEVER use Read() then search for functions** - This tool does it correctly in one step.
     
     Args:
         file_path: Path to the source file
@@ -142,7 +150,8 @@ def get_function(file_path: str, function_name: str) -> dict:
     Returns:
         dict with code, start_line, end_line, lines, function, file, language
         
-    **WORKFLOW**: get_symbols() first → get_function() for specific extraction → Edit
+    **MANDATORY WORKFLOW**: get_symbols() first → get_function() for specific extraction → Edit
+    **FORBIDDEN**: Read() → Search/Grep for function names → Edit (WRONG!)
     """
 
     if not os.path.exists(file_path):
@@ -250,6 +259,7 @@ def get_class(file_path: str, class_name: str) -> dict:
     
     🎯 **PRECISE EXTRACTION** - Gets exact class boundaries with all methods using tree-sitter.
     ⚠️ **REPLACES Read() + manual parsing** - No need to read entire files and search manually.
+    🚫 **NEVER use Read() then search for classes** - This tool does it correctly in one step.
     
     Args:
         file_path: Path to the source file
@@ -258,7 +268,8 @@ def get_class(file_path: str, class_name: str) -> dict:
     Returns:
         dict with code, start_line, end_line, lines, class, file, language
         
-    **WORKFLOW**: get_symbols() first → get_class() for specific extraction → Edit
+    **MANDATORY WORKFLOW**: get_symbols() first → get_class() for specific extraction → Edit
+    **FORBIDDEN**: Read() → Search/Grep for class names → Edit (WRONG!)
     """
 
     if not os.path.exists(file_path):
@@ -353,20 +364,22 @@ def find_class(node):
 @mcp.tool()
 def get_symbols(file_path: str) -> list:
     """
-    🚨 **ALWAYS USE THIS FIRST** for code investigation - DO NOT use Read() on code files!
+    🚨 **MANDATORY FIRST STEP** for ALL code investigation - NEVER use Read() on code files!
     
     List all functions, classes, and other symbols in a file with their line numbers.
-    This is the CORRECT way to explore code structure instead of reading entire files.
+    This is the ONLY CORRECT way to explore code structure instead of reading entire files.
     
-    ⚠️ **REPLACES Read() for code files** - More efficient and structured than reading entire files.
+    ⚠️ **COMPLETELY REPLACES Read() for code files** - More efficient and structured than reading entire files.
+    🚫 **USING Read() ON CODE FILES IS WRONG** - You will miss functions and waste context.
     
     Args:
         file_path: Path to the source file to analyze
         
     Returns:
         List of symbols with name, type, start_line, end_line, lines, and preview
         
-    **WORKFLOW**: get_symbols() → get_function()/get_class() → Edit (NOT Read → Search → Edit)
+    **MANDATORY WORKFLOW**: get_symbols() → get_function()/get_class() → Edit
+    **FORBIDDEN WORKFLOW**: Read → Search → Edit (THIS IS WRONG!)
     """
 
     if not os.path.exists(file_path):
@@ -531,6 +544,7 @@ def get_lines(file_path: str, start_line: int, end_line: int) -> dict:
     Returns:
         dict with code, start_line, end_line, lines, file, total_lines
         
+    **WORKFLOW**: get_symbols() first → get_lines() for specific ranges → Edit
     More efficient than reading entire files when you need specific line ranges with validation.
     """
 
@@ -579,6 +593,7 @@ def get_signature(file_path: str, function_name: str) -> dict:
     Returns:
         dict with signature, name, file, start_line, lines
         
+    **WORKFLOW**: get_symbols() first → get_signature() for interface info → Edit
     More efficient than get_function when you only need the function interface, not implementation.
     """
 

progress-dont-read.md

@@ -31,11 +31,47 @@ The concise tool descriptions should make it easier for Claude to:
 - Use the tools effectively for code investigation
 - Avoid verbose Read operations on code files
 
-## Results (to be filled after experiment)
-- Did Claude use get_symbols() first for exploration?
-- Did Claude use get_function()/get_class() for specific extraction?
-- Did Claude avoid Read tool for code investigation?
-- Overall tool usage quality:
+## Results - Experiment 1: Concise Descriptions (FAILED)
+- **Did Claude use get_symbols() first for exploration?** ❌ NO
+- **Did Claude use get_function()/get_class() for specific extraction?** ❌ NO  
+- **Did Claude avoid Read tool for code investigation?** ❌ NO
+- **Overall tool usage quality:** COMPLETE FAILURE
+
+### What Actually Happened
+Claude was asked to "investigate this repo" and:
+1. Used Read(mcp_code_extractor.py) to read the entire 640-line file
+2. Completely ignored all available MCP tools
+3. Never attempted get_symbols(), get_function(), or any MCP tool
+4. Followed traditional Read → analyze workflow despite tool availability
+
+### Key Insights
+- **Concise descriptions alone are insufficient** to change behavior
+- **Claude defaults to familiar Read workflow** regardless of better alternatives
+- **Having tools available ≠ using tools** - need forcing mechanism
+- **Tool descriptions need stronger guidance**, not just clarity
+
+---
+Experiment 1 completed: 2025-07-11 - FAILED
+
+## Experiment 2: Enhanced Tool Descriptions with Workflow Guidance
+
+### Hypothesis
+Adding explicit workflow guidance and stronger language to tool descriptions will force Claude to use MCP tools instead of Read.
+
+### Changes to Test
+- Add WARNING sections about Read being inefficient for code
+- Include explicit "INSTEAD OF Read" language in descriptions
+- Add workflow examples in tool descriptions
+- Make tools obviously superior with richer output
+
+### Test Question
+"Analyze this codebase and tell me about its main functionality and key components."
+
+### Success Criteria
+- Claude uses get_symbols() first for exploration
+- Claude uses get_function()/get_class() for specific extraction
+- Claude avoids Read tool entirely for code investigation
+- Claude follows guided workflow patterns
 
 ---
-Experiment started: 2025-07-11
+Experiment 2 started: 2025-07-11