Tool Selection Guide

This guide helps you choose the right tool from the 16 available MCP tools.

Quick Decision Tree

Reading Files

Do you need to read a file?
├── Full file → read_file
├── Specific line range → read_file with start_line + end_line
└── Binary/base64 → read_file with encoding:"base64"

Writing Files

Need to create or overwrite a file?
├── Text content → write_file
└── Binary/base64 → write_file with encoding:"base64" or content_base64

Editing Files

What kind of edit?
├── Single replacement → edit_file
├── Replace Nth occurrence → edit_file with occurrence:N
├── Regex-based transform → edit_file with mode:"regex"
├── Bulk replace across files → edit_file with mode:"search_replace"
└── Multiple replacements in one file → multi_edit

Searching

What are you looking for?
├── File name or content → search_files
├── Content with regex + context → search_files (with case_sensitive/whole_word/include_context)
├── Count occurrences only → search_files with count_only:true
└── Find and replace across files → edit_file with mode:"search_replace"

---

By Task Type

Reading and Viewing

Task	Tool	Why
Read any file	read_file	Auto-optimizes: direct for small, chunked for large
Read specific lines	read_file with start_line + end_line	Most token-efficient
Read first/last N lines	read_file with mode + max_lines	Tail logs, preview files
Read binary as base64	read_file with encoding:"base64"	Images, binaries

Editing and Modifying

Task	Tool	Why
Replace specific text	edit_file	Auto-backup, risk assessment, smart matching
Replace Nth occurrence	edit_file with occurrence:N	Precise control
Regex transformation	edit_file with mode:"regex"	Capture groups, advanced patterns
Bulk replace across files	edit_file with mode:"search_replace"	Recursive with file pattern filter
Multiple replacements	multi_edit	Atomic, single read/write cycle

Creating and Writing

Task	Tool	Why
Create or overwrite file	write_file	Auto-streams large content, creates dirs
Write binary from base64	write_file with encoding:"base64"	Images, binaries

Searching and Finding

Task	Tool	Why
Find files by name	search_files	Fast smart search
Find code in files	search_files with include_content	Content search
Regex with context lines	search_files with include_context	Advanced text search
Count matches	search_files with count_only:true	Quick count without reading

File Management

Task	Tool	Why
Rename file	move_file	Rename is a move within the same directory
Copy file	copy_file	Preserves permissions
Move file	move_file	Atomic move
Delete safely	delete_file	Soft-delete by default (recoverable)
Delete permanently	delete_file with permanent: true	Permanent
Get file info	get_file_info	Size, date, permissions

Directory Operations

Task	Tool	Why
List contents	list_directory	Fast, cached
Create directory	create_directory	Creates parents too

Backup and Recovery

Task	Tool	Why
View backups	backup	No params = list all
Backup details	backup with backup_id	Full info
Compare with backup	backup with backup_id + file_path	See differences
Clean old backups	backup with cleanup: true	Free space
Restore file	backup with action:"restore" + backup_id	Preview option with preview: true

Analysis and Planning

Task	Tool	Why
Analyze file	analyze_operation with operation: "file"	Size, type, strategy
Get optimization advice	analyze_operation with operation: "optimize"	Best approach
Preview edit impact	analyze_operation with operation: "edit"	Risk level
Preview write impact	analyze_operation with operation: "write"	Dry-run
Preview delete impact	analyze_operation with operation: "delete"	Impact analysis

WSL/Windows Integration

Task	Tool	Why
Copy between WSL/Windows	wsl with action:"sync" + source_path	Auto-detects direction
Sync workspace	wsl with action:"sync" + direction	Bidirectional sync
Check status	wsl with action:"status"	Environment info
Configure auto-sync	wsl with action:"status" + enabled	Toggle sync

Batch Operations

Task	Tool	Why
Multiple operations	batch_operations with request_json	Atomic with rollback
Rename many files	batch_operations with rename_json	8 rename modes
Multi-step pipeline	batch_operations with pipeline_json	Chained steps with conditions

Server Utilities

Task	Tool	Why
Performance stats	server_info with action:"stats"	Cache hit rates, throughput
Get help	server_info with action:"help"	Tool documentation
Capture artifact	server_info with action:"artifact"	Save/retrieve artifacts

---

Common Scenarios

Scenario 1: Fix a Bug in a Large File

1. search_files(".", "buggy_function") — Find location
2. read_file("file.go", start_line: 100, end_line: 120) — Read only that section
3. edit_file("file.go", "old_code", "fixed_code") — Apply fix

Scenario 2: Rename a Variable Everywhere

1. search_files("file.go", "oldName", count_only: true) — Check count
2. analyze_operation("file.go", "edit", old_text: "oldName", new_text: "newName") — Preview
3. edit_file("file.go", "oldName", "newName") — Apply

Scenario 3: Create Multiple Files Atomically

batch_operations({
  request_json: JSON.stringify({
    operations: [
      { type: "write", path: "file1.go", content: "..." },
      { type: "write", path: "file2.go", content: "..." },
      { type: "create_dir", path: "new_folder" }
    ],
    atomic: true
  })
})

Scenario 4: Recover from Mistake

1. backup() — List recent backups
2. backup({ backup_id: "...", file_path: "..." }) — Compare
3. backup({ action: "restore", backup_id: "...", preview: true }) — Preview
4. backup({ action: "restore", backup_id: "..." }) — Restore

Scenario 5: Regex Refactor with Capture Groups

edit_file({
  path: "handler.go",
  mode: "regex",
  pattern: "fmt\\.Errorf\\(\"(\\w+): %v\", err\\)",
  replacement: "fmt.Errorf(\"$1: %w\", err)"
})

Scenario 6: Multi-Step Pipeline

batch_operations({
  pipeline_json: JSON.stringify({
    name: "refactor-todos",
    stop_on_error: true,
    create_backup: true,
    steps: [
      { id: "find", action: "search", params: { path: ".", pattern: "TODO", file_types: [".go"] } },
      { id: "count", action: "count_occurrences", input_from: "find", params: { pattern: "TODO" } },
      { id: "fix", action: "edit", input_from: "find",
        condition: { type: "count_gt", step_ref: "count", value: "0" },
        params: { old_text: "TODO", new_text: "DONE" } }
    ]
  })
})

---

Performance Tips

Minimize Token Usage

1. Use search_files before reading large files — find the exact location first
2. Use read_file with start_line/end_line when you know the lines
3. Use edit_file instead of write_file for changes — sends only the diff
4. Use multi_edit for multiple changes in one file — single read/write cycle
5. Use batch_operations with pipeline_json for multi-step operations — 4x token reduction

Use Auto-Optimization

The consolidated tools automatically choose the best strategy:

• read_file — Direct read or chunked streaming based on file size
• write_file — Direct write or streaming write based on content size
• edit_file — Direct edit or line-by-line streaming based on file size

Use Caching

• Directory listings are cached (98%+ hit rate)
• Repeated reads of same file use cache
• Use server_info with action:"stats" to check cache performance

---

Migration from v3 (59 tools) to v4 (16 tools)

Old Tool (v3)	New Tool (v4)	How
mcp_read	read_file	Same params
mcp_write	write_file	Same params
mcp_edit	edit_file	Same params
mcp_search	search_files	Same params
mcp_list	list_directory	Same params
read_file_range	read_file	Add start_line + end_line
read_base64	read_file	Add encoding:"base64"
write_base64	write_file	Add encoding:"base64"
rename_file	move_file	Same params (rename = move)
search_and_replace	edit_file	Add mode:"search_replace"
replace_nth_occurrence	edit_file	Add occurrence:N
regex_transform_file	edit_file	Add mode:"regex"
count_occurrences	search_files	Add count_only:true
execute_pipeline	batch_operations	Pass pipeline_json instead of request_json
batch_rename_files	batch_operations	Pass rename_json instead of request_json
restore_backup	backup	Add action:"restore"
wsl_sync	wsl	Add action:"sync"
wsl_status	wsl	Add action:"status"
stats	server_info	Add action:"stats"
get_help	server_info	Add action:"help"
artifact	server_info	Add action:"artifact"

---

Tool Categories Summary

Category	Count	Tools
Reading	1	read_file
Writing	1	write_file
Editing	2	edit_file, multi_edit
Search	1	search_files
File Ops	4	copy_file, move_file, delete_file, get_file_info
Directory	2	list_directory, create_directory
Analysis	1	analyze_operation
Backup	1	backup
WSL	1	wsl
Batch	1	batch_operations
Utilities	1	server_info

Total: 16 tools