Better Finder MCP has clear tool naming following verb-noun convention (search_files, index_files, get_file_content, get_stats, configure_paths). All 5 tools are explicitly defined with input schemas visible in mcp_server.py. However, tool descriptions are generic and lack critical context for LLM decision-making. Parameter descriptions exist but are minimal, most lack validation guidance, ranges, or format specifications. No output schemas are documented, making it impossible for LLMs to plan chained operations. Error handling and recovery guidance are absent. Tool composition is reasonable (each handles one concern), but lacks the detail required for production-grade agent interaction.

• Document output schemas for all tools. Example for search_files: 'Returns {files: [{path: string, name: string, type: string, relevance_score: float, preview: string}], total: int, search_time_ms: int}'. This enables downstream chaining.
• Expand tool descriptions to 80-150 characters explaining: (1) What does it do? (2) When should I call it? (3) What do I get back? Example: 'Search indexed files by keyword or semantic meaning. Use after calling index_files. Returns matching file paths, types, and relevance scores (1-10). Limit results with max_results parameter.'
• Add validation guidance to parameter descriptions. For 'query': 'Search term (1-256 chars, supports wildcards * and ?). Example: *.pdf or invoice_2024'. For 'max_results': 'Number of results to return (1-100, default 10). Larger values increase latency.'
• Add dry-run support to index_files and configure_paths. Example: add 'dry_run: boolean' parameter with description 'If true, preview changes without applying (recommend for first call)'. This prevents accidental full reindex or deletion.
• Document error scenarios and recovery paths. Example in search_files description: 'If no results returned, call index_files() to build the index, or expand the query. If indexing is slow, check file count via get_stats().'
• Clarify get_file_content truncation behavior. Add to description: 'Returns up to max_length characters. If file is larger, response includes is_truncated: true and next_offset for pagination.'
• Clarify configure_paths dependencies. Document: 'For action="list", path parameter is ignored. For "add"/"remove", path is required and must be an absolute directory path.'