MCP Server for Claude Desktop integration providing file search, analysis, organization, and disk management capabilities with multimedia content support
Significant quality gaps across tool definitions. While 20 tools are declared with names and basic descriptions, most lack proper parameter documentation, and several show incomplete or missing schemas. Parameter descriptions are sparse or absent. Output schemas are not documented. Error handling is minimal. The server shows basic structure but falls well short of production-grade tool design. Average per-tool score: 42/100.
Missing or incomplete parameter descriptions across nearly all tools. Parameters like 'media_types', 'categories', 'by', 'days', 'file_id', 'task_id' have minimal or no explanatory text for LLMs to understand valid values, format, or constraints.
No output schemas documented for any tool. LLMs cannot infer what fields will be returned, preventing them from planning downstream calls or extracting relevant data. Example: does search_files return file_path, file_id, file_size, metadata, or all of these?
Add explicit output schema (type, fields, field types) to EVERY tool definition. Minimum: return type (object, array, string), key fields, and field descriptions. Example for search_files: {type: 'array', items: {type: 'object', properties: {file_id: {type: 'string'}, file_path: {type: 'string'}, size: {type: 'number'}, matched_content: {type: 'string'}}}
Expand tool descriptions from current ~40-50 chars to 100-250 chars. Include: WHAT the tool does, WHEN to use it (vs similar tools), WHAT it returns, and any prerequisites. Example: 'Search files by content, name, metadata, or AI-based visual similarity. Use this first to discover files matching user intent. Returns up to 20 results with file paths, sizes, and relevance scores. Requires media_types filter for large repositories.' (This is ~150 chars.)
Add non-empty descriptions to ALL parameters. Do not leave media_types, categories, by, days, file_id, task_id undescribed. For each: state what it controls, valid values or format, and why it matters. Example for 'by' (find_duplicates): 'Comparison method: hash (content-based, slowest but most accurate), name (string match), or size (byte match, fastest). Default hash.'
Declare constrained parameters as formal JSON Schema enums. Example for organize_files 'action' (if it exists): {type: 'string', enum: ['move', 'link', 'copy'], description: 'How to organize: move (physical relocate), link (symbolic link), or copy (duplicate). Default: move.'}
Add result limits and pagination for list_directory and search_files. Add 'limit' param (1-100, default 20) and 'offset' param (default 0). Return total count and next_offset for paging. Document this in tool description.
Enums not consistently declared for constrained parameters. find_duplicates 'by' param accepts 'hash|name|size' as enum, but analyze_file 'analysis_type' uses enum while many other constrained params lack formal enum declarations, inviting hallucinated values.
No error recovery guidance. Tools declare no error handling strategy. No indication whether failures are retryable, user-fixable, or fatal. No suggested next steps if a tool fails (e.g., 'file not found, try search_files first').
Destructive operations lack confirmation/dry-run pattern. delete_file has a 'permanent' flag but no mention of dry-run mode or confirmation requirement. cleanup_thumbnails and cleanup_temp offer no preview before destructive action.
Tool descriptions too generic or too brief. Examples: 'Get disk cleanup recommendations' (35 chars), 'Clean temporary files' (21 chars), 'Get system health and API status' (32 chars).
No pagination or result limits documented for list_directory or search_files. If a directory has thousands of files or search returns 10k results, LLMs could be overwhelmed.
Parameter 'file_id' and 'task_id' appear in multiple tools but are never defined. What format is a file_id? Is it a UUID, numeric ID, or path string? LLMs cannot reason about ambiguous identifiers.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). While tools are marked with Risk: READ_ONLY, WRITE, or IRREVERSIBLE in metadata, these hints should be formally declared in the MCP protocol for client safety.
No idempotency guarantees stated. If an agent retries move_file or copy_file on timeout, will it create duplicates or fail gracefully? Without idempotency declarations, agents cannot safely retry.
No chaining IDs returned. If search_files returns matching files, the response must include file_id and file_path so the agent can immediately call analyze_file or get_file_info without extra lookup steps.
For destructive tools (delete_file, cleanup_thumbnails, cleanup_temp), add 'dry_run' parameter (boolean, default true). When true, preview changes without executing. Example: 'Preview: would delete 47 thumbnails (total 2.3 GB). Set dry_run=false to confirm.' This prevents accidental data loss.
Add error recovery guidance to error responses. Instead of 'File not found', return: 'File not found at "/path/to/file.txt". Try search_files(query="filename") to locate it, or list_directory("/parent/path") to check available files.'
Define file_id and task_id format explicitly. Is file_id a UUID (36 chars), numeric (e.g., 12345), or path string? Update parameter descriptions. Example: 'file_id (UUID v4, e.g., 550e8400-e29b-41d4-a716-446655440000): unique file identifier from search_files or get_file_info results.'
Ensure tool chaining works: if search_files returns results, each result MUST include file_id and file_path so agent can call analyze_file, get_file_info, or move_file without extra lookups. Example response: [{file_id: '...', file_path: '/home/user/docs/report.pdf', size_bytes: 204800, relevance: 0.95}]
Add tool annotations (toolAnnotations feature in MCP spec). Mark each tool with readOnlyHint, destructiveHint, or idempotentHint to signal safety to clients and prevent accidental misuse.
State idempotency guarantees. Example: 'Idempotent: calling move_file with the same source and destination twice returns success both times without creating duplicates.' Or 'Non-idempotent: retry may duplicate files if network error occurs; use dry_run first to verify state.'
For organize_files, clarify what 'AI-based organization' means: does it use image vision, text analysis, or both? What categories does it suggest? Example: 'AI uses filename, file type, and (for images) visual content analysis to suggest new organization. Suggests categories: Work, Personal, Archive, Media, Documents. Output lists proposed moves as: {source: '/path/a.jpg', target: '/Media/2024/Jan/a.jpg', reason: 'image from camera, detected January 2024'}.'
Add batch variants for frequently-looped operations. Example: analyze_file should accept file_paths as array for batch processing, returning [{file_id, analysis_result}]. Reduces token cost and latency vs N sequential calls.
Document dependency relationships between parameters. Example for search_files: 'If include_ai_analysis=true and analysis_type=auto, the tool will attempt to detect type (image, video, audio, document) automatically. For guaranteed type detection, set analysis_type explicitly.'
Add minimum/maximum constraints for numeric params. Example cleanup_thumbnails 'days': {type: 'number', minimum: 1, maximum: 3650, default: 30, description: 'Remove files older than N days (1-3650, e.g., 30 for 1 month). Default 30.'}
Standardize response format across all tools. Return consistent fields: status (success|partial|error), data (actual result), errors (if partial), metadata (count, next_offset for paginated, etc.). Example: {status: 'success', data: [...], metadata: {total: 1500, returned: 20, next_offset: 20}}