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

# 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.