Bug #8: Help System

Status: RESOLVED in v3.7.0 Category: Developer Experience Severity: Medium (Efficiency limitation) Resolution Date: December 2025

Problem

Claude Desktop and other AI agents using the MCP server had no way to learn the optimal workflows for file operations. Each session, Claude would:

1. Discover tools through trial and error
2. Use inefficient patterns (full file rewrites instead of surgical edits)
3. Waste tokens on suboptimal approaches
4. Repeat the same mistakes across sessions

Impact

• Inconsistent tool usage across sessions
• High token consumption from inefficient workflows
• Claude would often read entire large files instead of using read_file_range
• No guidance on when to use streaming vs normal operations
• Users had to repeatedly explain optimal patterns

Symptoms

User: "Edit line 500 of this 10,000 line file"

Claude (without help system):
  1. read_file("large.go")           # 250,000 tokens
  2. [processes entire file]
  3. write_file("large.go", ...)     # 250,000 tokens

Total: ~500,000 tokens for a 1-line change

Root Cause

The MCP server provided tools but no documentation on how to use them efficiently. AI agents had to discover optimal patterns through experience, which was lost between sessions.

Solution

New Tool: get_help

Added a self-learning help system that provides structured guidance on optimal workflows.

Tool Definition:

getHelpTool := mcp.NewTool("get_help",
    mcp.WithDescription("Get usage instructions for MCP tools. Call this FIRST to learn optimal workflows."),
    mcp.WithString("topic", mcp.Description("Topic: overview, workflow, tools, read, write, edit, search, batch, errors, examples, tips, all")),
)

Available Topics

Topic	Description
overview	Introduction and key principle (surgical edits save 98% tokens)
workflow	The 4-step efficient workflow (LOCATE, RANGE, EDIT, VERIFY)
tools	Complete list of 56 available tools by category
read	Reading files efficiently (ranges, chunked reads)
write	Writing and creating files
edit	Editing files (most important for token savings)
search	Search operations and filters
batch	Batch operations and artifacts
errors	Common errors and solutions
examples	Code examples for common tasks
tips	Pro tips for maximum efficiency
all	Complete documentation (long output)

The 4-Step Workflow

The help system teaches this efficient pattern:

Step 1: LOCATE
smart_search({path: ".", pattern: "functionName", include_content: true})
Result: file.go:142 (1 match)

Step 2: RANGE READ
read_file_range({path: "file.go", start: 140, end: 150})
Result: 10 lines of context (200 tokens)

Step 3: SURGICAL EDIT
edit_file({path: "file.go", old_text: "...", new_text: "..."})
Result: Precise change (100 tokens)

Step 4: VERIFY (Optional)
get_edit_telemetry()
Result: Confirm >80% targeted edits

New Capabilities

Example Usage

// Claude's first action in a session
get_help({topic: "overview"})

Response:

CORE PRINCIPLE: Surgical Edits Save 98% Tokens

BAD:  read_file(large) -> write_file(large) = 250k tokens
GOOD: smart_search -> read_file_range -> edit_file = 2k tokens

AVAILABLE TOPICS:
Call get_help(topic) with:
- "workflow" - The 4-step efficient workflow
- "tools"    - Complete list of 50 tools
- "read"     - Reading files efficiently
- "edit"     - Editing files (most important!)
...

Topic: Edit (Most Important)

get_help({topic: "edit"})

Response:

EDITING FILES EFFICIENTLY

RULE: Never read entire file just to change a few lines!

EFFICIENT EDIT WORKFLOW:
1. smart_search to find the code location
2. read_file_range to see just that section
3. edit_file with minimal old_text/new_text

AVAILABLE EDIT TOOLS:
- edit_file - Basic surgical edit
- smart_edit_file - Large file streaming edit
- multi_edit - Multiple edits in one call
- recovery_edit - Handles whitespace/encoding issues
- intelligent_edit - Auto-selects best strategy
...

Benefits

Token Reduction

Before (without help):

Session starts
Claude: [No guidance, uses trial-and-error]
  read_file(10MB file)     # Timeout or 250k tokens
  write_file(10MB file)    # Another 250k tokens

Average session: 500k-1M tokens

After (with help):

Session starts
Claude: get_help("workflow")    # 500 tokens
Claude: [Follows 4-step pattern]
  smart_search              # 100 tokens
  read_file_range           # 200 tokens
  edit_file                 # 100 tokens

Average session: 50k-100k tokens

Result: 80-90% token reduction when Claude follows the documented patterns.

Consistent Behavior

• Claude learns optimal patterns at session start
• Same efficient workflow every time
• No more trial-and-error discovery
• Users don’t need to explain patterns repeatedly

Files Modified

1. main.go

   • Lines 1787-1800: get_help tool definition and registration
   • Lines 2049-2500: getHelpContent() function with all topic content

2. README.md - Updated tool list

3. CHANGELOG.md - Added v3.7.0 entry

Implementation Details

The help system is implemented as a large switch statement that returns topic-specific guidance:

func getHelpContent(topic string) string {
    var sb strings.Builder

    switch strings.ToLower(topic) {
    case "overview", "":
        sb.WriteString(`# MCP FILESYSTEM ULTRA-FAST - USAGE GUIDE

CORE PRINCIPLE: Surgical Edits Save 98% Tokens
...`)
    case "workflow":
        sb.WriteString(`# 4-STEP EFFICIENT WORKFLOW
...`)
    // ... more topics
    }

    return sb.String()
}

Backward Compatibility

100% backward compatible:

• New tool, no changes to existing tools
• Optional - agents can ignore it
• No breaking changes

Resolution Timeline

• Discovered: December 2025
• Fixed: December 2025
• Released: v3.7.0
• Status: Production Ready

Lessons Learned

1. Documentation is a feature - AI agents need guidance just like human developers
2. Teach patterns, not just tools - Knowing what tools exist isn’t enough; agents need workflow guidance
3. Make help accessible - A get_help tool is more discoverable than external documentation
4. Front-load learning - Encourage agents to call get_help first to set up efficient patterns