Code Sage has 4 tools with partial schema definitions visible in the source. All 4 tools have descriptions (good), but schema completeness varies. analyze_code, find_code, and delete_index have input schemas with type info and parameter descriptions. check_status also has a schema. However, NONE of the tools have documented OUTPUT schemas, a critical gap for composition and LLM planning. Tool naming is verb-noun (analyze_, find_, delete_, check_) which is correct. The descriptions are adequate in length (50-200 chars) but lack dependency hints and recovery guidance. Parameter descriptions are present but minimal. The risk annotations (WRITE, READ_ONLY, DESTRUCTIVE) are helpful but not part of the MCP tool definition spec, they appear to be internal metadata. Overall, the definitions show competence in basics but lack the depth and completeness for A-grade production use.

• Add documented output schemas for all 4 tools. Include fields returned, types, and examples. At minimum: analyze_code should return {indexed_paths, files_processed, chunks_created, status}; find_code should return {results: [{path, function_name, score, line_number}], total_count, has_more}; delete_index should return {deleted: boolean, path, message}; check_status should return {status: 'idle'|'indexing'|'failed', percentage_complete, files_processed, total_files, error_message}.
• Add recovery guidance to descriptions. E.g., find_code: 'If no results found, ensure analyze_code() has completed via check_status(). Results may be incomplete while indexing is in progress.'
• For find_code limit param, add constraint: 'Maximum 1000, recommended 20 - 50. Higher limits slow response and increase token consumption.'
• For analyze_code force param, clarify default: 'If force=false (default) and codebase already indexed, performs incremental update. If force=true, deletes existing index and re-indexes from scratch.'
• For delete_index, implement dry-run or confirmation: add optional 'confirm' boolean param. If confirm=false (default), return {would_delete: true, path, warning: 'Call with confirm=true to actually delete'} without deleting. Or add a separate preview_delete_index tool.
• Document all 'path' parameters consistently: 'Absolute filesystem path to codebase directory. Must be readable by the server process. Path will be resolved and validated before indexing.'
• Clarify error handling: describe what the tools return on error (JSON with 'error' field?). Provide examples of common errors: 'Path not found', 'Permission denied', 'Invalid syntax in codebase', 'Indexing already in progress'.

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

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