AdvancedFileSystem has clear verb-based naming (list_, read_, write_, delete_, search_) and all tools include descriptions. However, parameter descriptions are minimal (1-2 sentences), output schemas are not documented, and error handling lacks recovery guidance. The safe_path() validation is solid, but tools return unstructured strings rather than typed objects. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. Descriptions average ~60 chars, below the 194-char baseline for A+ tools. Parameters lack constraints (e.g., no max file size for write_file, no limit on search results).

• Add tool annotations: @mcp.tool(..., annotations={'readOnlyHint': True}) for list_files/read_file; @mcp.tool(..., annotations={'destructiveHint': True}) for delete_file; @mcp.tool(..., annotations={'destructiveHint': True}) for write_file (overwrites existing).
• Document output schemas. Return typed dicts instead of strings: list_files → {entries: [{name: str, type: 'file'|'dir', path: str}], total: int}; read_file → {content: str, encoding: str, size_bytes: int}; search_files → {matches: [{file: str, line_number: int, line_text: str}], total_matches: int}.
• Add parameter constraints: write_file(content: str with max 10MB), search_files(limit: int 1-1000, default 100), list_files(subdir: str matching ^[a-zA-Z0-9_./\-]*$).
• Enhance error messages with recovery hints: 'File not found: {file_path}. Call list_files() to see available files.' Return available alternatives when resource not found.
• Add dry-run support to delete_file: delete_file(file_path: str, dry_run: bool = True) to let agents preview before committing. Require explicit dry_run=False to execute.