enhanced-mcp-tools/docs/LLM_TOOL_GUIDE.md

# LLM Tool Annotations Guide

**Note**: This project is prepared for FastMCP's new ToolAnnotations feature (available in main branch). Until that's released, this guide serves as reference for LLM clients.

## Tool Safety Categories

### 🟢 **SAFE - Read-Only Tools**
These tools only read data and never modify files or system state:

- `diff_generate_diff` - Compare files/directories, safe to run anytime
- `git_git_status` - Check git repository status
- `git_git_diff` - View git changes and diffs
- `search_analyze_codebase` - Analyze code metrics (LOC, complexity, dependencies)
- `search_find_duplicates` - Find duplicate files using hash comparison
- `dev_run_tests` - Execute tests (doesn't modify code)
- `dev_lint_code` - Check code quality with linters (when fix=False)
- `trace_trace_process` - Monitor process activity (read-only)
- `trace_analyze_syscalls` - Analyze system call traces
- `trace_process_monitor` - Real-time process monitoring
- `env_environment_info` - Get system/environment info
- `env_process_tree` - Show process hierarchy
- `enhanced_search_code_enhanced` - Advanced code search
- `util_dependency_check` - Analyze project dependencies

### 🟡 **CAUTION - File Creation Tools**
These tools create new files but don't modify existing ones:

- `diff_create_patch_file` - Creates patch files from edits
- `file_file_backup` - Creates backup copies of files
- `archive_create_archive` - Create compressed archives
- `util_generate_documentation` - Generate documentation files

### 🟠 **WARNING - Potentially Destructive Tools**
These tools can modify or create files/directories. Use with care:

- `file_watch_files` - Monitors files (safe) but returns watch IDs
- `net_http_request` - HTTP requests (read-only for GET, potentially destructive for POST/PUT/DELETE)
- `net_api_mock_server` - Start mock server (creates server process)
- `archive_extract_archive` - Extract archives (creates files/directories)
- `env_manage_virtual_env` - Create/manage Python environments

### 🔴 **DESTRUCTIVE - Dangerous Tools**
These tools modify existing files or system state. **Always use dry_run=True first when available!**

- `diff_apply_patch` - Modifies files! Use dry_run=True first
- `git_git_commit_prepare` - Stages files for git commit
- `file_bulk_rename` - Renames files! Use dry_run=True first
- `search_search_and_replace_batch` - Modifies files! Use dry_run=True first
- `dev_format_code` - Formats/modifies code files
- `enhanced_edit_block_enhanced` - Advanced multi-file editing
- `util_project_template` - Creates entire project structure

### ⛔ **EXTREMELY DANGEROUS - Hidden Parameters**
These tools have dangerous parameters hidden from LLM:

- `dev_lint_code` - Hidden `fix` parameter (can modify files)
- `trace_trace_process` - Hidden `target` parameter (security)
- `enhanced_execute_command_enhanced` - Hidden `command` parameter (can execute anything)

## Tool Usage Guidelines for LLMs

### Always Preview Before Modifying
For any destructive tool, ALWAYS:
1. Use `dry_run=True` first to preview changes
2. Review the preview results with the user
3. Only proceed with actual changes if user confirms

### Safe Default Practices
- Start with read-only tools to understand the codebase
- Use `file_file_backup` before making changes
- Prefer `git_git_status` and `git_git_diff` to understand changes
- Use `search_analyze_codebase` to understand project structure

### Error Handling
- All tools include comprehensive error handling
- Check for error messages in return values
- Many tools will gracefully skip missing files/directories

### Progress Reporting
- Long-running tools report progress when possible
- Tools use Context logging for detailed operation tracking

## Example Safe Workflow

```python
# 1. Understand the project
await search_analyze_codebase(directory=".", include_metrics=["loc", "dependencies"])

# 2. Check git status
await git_git_status(repository_path=".")

# 3. Preview changes (if needed)
await search_search_and_replace_batch(
    directory=".", 
    search_pattern="old_pattern", 
    replacement="new_pattern",
    dry_run=True  # ALWAYS preview first
)

# 4. Create backup before changes
await file_file_backup(file_paths=["important_file.py"])

# 5. Apply changes only after user confirmation
await search_search_and_replace_batch(
    directory=".", 
    search_pattern="old_pattern", 
    replacement="new_pattern",
    dry_run=False,  # Only after preview and confirmation
    backup=True
)
```

## Tool Categories by Function

### Development Workflow
- **Testing**: `dev_run_tests` (safe)
- **Code Quality**: `dev_lint_code` (safe), `dev_format_code` (destructive)
- **Project Analysis**: `search_analyze_codebase` (safe)

### Git Integration
- **Status**: `git_git_status` (safe), `git_git_diff` (safe)
- **Staging**: `git_git_commit_prepare` (destructive - stages files)

### File Operations
- **Monitoring**: `file_watch_files` (safe)
- **Backup**: `file_file_backup` (safe - creates copies)
- **Rename**: `file_bulk_rename` (destructive - use dry_run first)

### Search & Replace
- **Analysis**: `search_analyze_codebase` (safe), `search_find_duplicates` (safe)
- **Modification**: `search_search_and_replace_batch` (destructive - use dry_run first)

### Network & APIs
- **HTTP**: `net_http_request` (depends on method)
- **Mock Server**: `net_api_mock_server` (creates process)

### Archives
- **Create**: `archive_create_archive` (safe - creates new files)
- **Extract**: `archive_extract_archive` (destructive - creates files)

### System Monitoring
- **Processes**: `env_process_tree` (safe), `trace_process_monitor` (safe)
- **Environment**: `env_environment_info` (safe)
- **Virtual Envs**: `env_manage_virtual_env` (destructive when creating)

This guide ensures LLMs can use the tools safely and effectively even before the official ToolAnnotations feature is available.