mcp-codesearch demonstrates solid fundamentals with 12 clearly-named tools using consistent verb_noun conventions (list_*, delete_*, search_*, find_*, code_*, repair_*, etc.). All tools have descriptions present. However, significant gaps exist: (1) Parameter descriptions are minimal or missing for several tools, e.g., cleanup_orphans has NO input schema visible despite being a destructive tool; (2) Output schemas are entirely undocumented, the code shows tools returning results but never specifies what fields/structure agents should expect; (3) Error handling is not documented in any tool description; (4) Some parameter descriptions lack actionable constraints (e.g., 'collection' in delete_collection is just 'Collection name to delete' with no guidance on valid formats, length, or recovery if wrong). The naming is generally strong ('code_search', 'find_references', 'search_changed' are all clear and action-oriented), and tool composition appears reasonable (search vs. index vs. delete are separate). Risk annotations (READ_ONLY, DESTRUCTIVE, WRITE) are present in metadata but not reflected in schema-level destructiveHint/idempotentHint tool annotations. Descriptions are functional but brief (most 40-80 chars), lacking the 50-200 char optimized range that helps LLMs reason about tool selection.

• Add comprehensive output schema documentation to every tool. For code_search, document: 'Returns array of {file_path: string, line_number: integer, snippet: string, score: float}' or similar. Use the indexing_service.py code to reverse-engineer the actual output structure and expose it in tool descriptions or a separate schema reference.
• Expand all parameter descriptions to include actionable constraints. Template: 'Parameter name (type, constraint): purpose. Example: <valid_value>. If invalid, <recovery_action>.' Example for 'collection': 'Collection name (string, 1-255 chars, alphanumeric + dash): The indexed codebase name. If not found, call list_collections first.'
• Add tool annotations (destructiveHint, readOnlyHint) to schema definitions. The risk metadata exists in the evaluator summary; surface it in the actual tool definitions so clients can flag destructive operations. For delete_collection and cleanup_orphans, add destructiveHint=true.
• Implement confirmation pattern for destructive operations. For delete_collection, add a 'confirm' boolean parameter (default false) that returns a confirmation hash on first call; require that hash on the actual delete call. Or offer a dry_run parameter for preview before execution.
• Enhance search tool descriptions with mutual-exclusion guidance. E.g., 'Use code_search for natural-language semantic queries. Use find_references for symbol-based lookups. Use find_similar for code-snippet matching.' This helps agents pick the right tool on first try.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry