mcp-workspace provides 4 reference project tools with solid naming (verb_noun pattern) and descriptions. However, there are notable gaps: parameter descriptions are present but some lack clarity on constraints; output schemas are not explicitly documented in the source; error handling guidance is minimal; and some parameters (context_lines, max_results) lack range specifications. The tools follow a consistent read-only reference pattern, which is appropriate for the use case, but descriptions could be more LLM-optimized per the 50-200 char baseline.

• Add explicit JSON Schema definitions for all tool outputs in the FastMCP tool registration. Each tool should document its return type: e.g., get_reference_projects returns a list of {name: string, url: string} objects.
• Add min/max constraints to numeric parameters. E.g., for search_reference_files: 'context_lines: number of lines of context around matches (0 - 10, default 0)', 'max_results: maximum matches to return (1 - 500, default 50)', 'max_result_lines: maximum total output lines (1 - 5000, default 200)'.
• Enhance parameter descriptions with format hints and dependencies. E.g., 'reference_name: Name of the reference project (must match exactly from get_reference_projects; case-sensitive)' and 'start_line and end_line must be used together; omit both for full file read'.
• Document error conditions and recovery steps in tool descriptions. E.g., 'If the reference project is not available locally, get_reference_projects will list only cached projects. Use ensure_available() to fetch missing projects.' (or similar guidance visible to the LLM).
• Add a discovery-oriented parameter (e.g., list_reference_directory description) to guide LLM on when to use it vs. search (for broad exploration vs. targeted keyword search).

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

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