Virgil exhibits solid fundamentals: all 6 tools have action-verb names (scan_, check_, analyze_, generate_, fetch_, search_), documented descriptions (130-180 chars), and complete JSON Schema input specifications with typed parameters and per-parameter descriptions. Tool naming follows verb_noun convention clearly. However, output schemas are entirely undocumented, the code shows tools return JSON-encoded results via TextContent but reveals nothing about the structure LLMs will receive. Error handling is generic ('tool_name failed: $e') with no recovery guidance or actionable next steps. Parameter descriptions lack specificity: 'analysiDepth' explains enum options but doesn't state what happens when analysis reaches line_level; 'resolveTypes' says 'slower but more precise' without quantifying cost or when to use it. No evidence of pagination for list results or result-size caps. Tool composition is sound (each does one thing), but lacks chaining hints, fetch_changelog doesn't mention that its output feeds into analyze_upgrade_impact. Overall quality is above-average community baseline but falls short of production-grade due to missing output schemas and weak error guidance.

• Document output schemas for all 6 tools. For each tool, add a 'returns' section to the description or register an outputSchema with the MCP server. Example for scan_project: 'Returns {dependencies: [{name: string, currentVersion: string, constraint: string, isDev: boolean, isTransitive: boolean}], sdkRequirements: {flutter?: string, dart?: string}}'.
• Replace generic error handling with categorized, actionable errors. For each tool, catch specific exception types and return structured error responses. Example: if projectPath doesn't exist, return 'Project not found at /path/to/project. Verify the path is absolute and the project root contains pubspec.yaml.' For network errors, return 'Failed to fetch package metadata (network timeout). Check your internet connection and retry.'
• Add performance and tradeoff guidance to parameter descriptions. Example for 'resolveTypes': 'If true (default), performs full type resolution for higher accuracy but adds ~2-5s latency for large codebases. Set to false for quick searches in simple projects.' Example for 'includeTransitive': 'If true, includes transitive deps from pubspec.lock (complete view but longer results). If false, shows only direct deps from pubspec.yaml (faster, cleaner for quick reviews).'
• Implement and document pagination for tools that return lists. For check_available_upgrades and search_api_usage, add optional limit and offset parameters. Document max result sizes (e.g., 'Returns up to 50 results per call. Use offset to paginate.'). Return a total_count field so agents know if more results exist.

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

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