Server has 10 tools with mixed definition quality. Tool names follow verb_noun convention (get_, list_, watch_, acknowledge_, resolve_). However, critical gaps exist: 6 tools lack visible input schemas in source code (only inferred from .well-known/mcp.json), descriptions are generic (avg ~80 chars, below 194-char baseline), and parameter descriptions are sparse or missing. No output schemas documented. Error handling and recovery guidance absent. Tools like watch_performance and watch_for_issue lack timeout validation details. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels.

• Add explicit input schema definitions to packages/mcp/src/mcpServer.ts for all 10 tools. Include type, description, and constraints for every parameter. Example: project_id should document 'optional when exactly one project is active' as a conditional requirement, not just a note.
• Expand tool descriptions from ~80 chars to 150-250 chars. Include WHAT (what does it do), WHEN (when should LLM call it), and WHAT IT RETURNS (what structure). Example: 'get_performance_snapshot' → 'Retrieves the latest browser performance metrics including frame rate, Core Web Vitals (LCP, FID, CLS), memory usage, and resource counts. Call this after code changes to verify performance impact. Returns structured object with numeric metrics and detected issue list.'
• Document output schemas for all tools. For get_detected_issues, specify: returns array of {issue_id, severity, detector_name, description, affected_element}. For get_performance_snapshot, specify: {frame_rate_fps, lcp_ms, fid_ms, cls_score, memory_mb, resource_count, detected_issues[]}.
• Add tool annotations to schema: readOnlyHint=true for 8 read-only tools, destructiveHint=true for acknowledge_issue/resolve_issue/release_project (state-modifying), idempotentHint=true for get_* tools. This enables LLM to reason about safety and retry logic.
• Add error handling guidance to tool descriptions. Example for watch_performance: 'Returns timeout error if no snapshot received within timeout_seconds. Retryable. If repeated timeouts occur, project may be inactive, call list_projects to verify.' For acknowledge_issue: 'Returns 404 if issue_id not found in project. Returns 409 if issue already acknowledged. Idempotent, safe to retry.'