Code Lens defines 13 tools with explicit schemas, descriptions, and parameter contracts visible in src/lib/tool-contracts.ts. However, several critical gaps reduce the score: (1) Tool descriptions vary widely in specificity and don't uniformly answer WHAT/WHEN/WHY with actionable guidance; (2) Parameter descriptions are present but often generic (e.g., 'Primary language hint' for language param across multiple tools); (3) Output schemas are documented as string fields in the contract ('outputShape' field) but are not formally defined, tool callers cannot know the exact return structure; (4) Error handling guidance is absent, no indication of what errors are retryable, how to recover, or what to do if analysis fails; (5) Some tools combine multiple concerns (e.g., analyze_pr_impact analyzes severity, breaking changes, AND rollback complexity in one tool); (6) Dependencies between tools are documented in crossToolFlow but not in parameter descriptions; (7) No confirmation/dry-run pattern for potentially high-impact analyses. The tool naming is good (verb_noun pattern), and schemas are properly typed with constraints, which prevents a lower score. This is a C+/B- server, solidly functional but missing production-grade polish around error guidance and output shape documentation.

• Document the output schema for ALL tools. For each tool, add a formal JSON Schema (or description) of the returned object. Example: 'Returns: {"summary": string, "risk_rating": "low"|"medium"|"high", "merge_recommendation": "merge"|"request_changes"|"hold"}'. This enables LLMs to plan downstream calls.
• Add explicit error handling guidance to every tool description. Example: 'Errors: If the diff is empty (no changes detected), returns empty analysis. If code is malformed, returns partial analysis with flagged sections. Always retryable; no side effects.'
• Integrate tool dependencies directly into descriptions. For tools with requiresDiff or requiresFile, add a sentence like 'Prerequisite: Call generate_diff() first and cache the result. This tool analyzes the cached diff.'
• Refine parameter descriptions to be context-specific. Instead of 'Primary language hint' for language, try: 'Programming language of the changed code (e.g., "python", "typescript"). Used to select analysis rules. If omitted, auto-detected from file extensions.'
• Separate concerns in verify_logic. Either rename it to clarify its true purpose (query-based validation? proof of correctness?) or split it into dedicated tools. The current name and parameter do not align.
• Add result limits to search_codebase and any other tools that return lists. State in the description: 'Returns up to 50 results. If more matches exist, use topic parameter to narrow the search.'
• Add response examples (non-executable) in tool descriptions to illustrate expected output structure. Example: 'Response includes fields: detected_changes (array of {type, location, severity}), breaking_changes (array of strings), rollback_risk ("low"|"medium"|"high").'

Inferred effective spec: 2025-06-18+.

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