Nerq MCP Server has well-structured tool definitions with clear names, strong descriptions, and comprehensive input schemas. All 5 tools follow verb_noun naming conventions and include detailed descriptions explaining WHAT the tool does, WHEN to use it, and guidance on alternatives. Input schemas are properly defined with type constraints and enums. However, output schemas are NOT documented in the provided code, which is a critical gap, LLMs cannot plan downstream calls without knowing the structure of returned data. Additionally, there are no parameter validation descriptions (e.g., format constraints, ranges) beyond what's in the schema itself, and error handling guidance is absent from tool descriptions.

• Add explicit response schema documentation for all 5 tools. Each tool description should include a 'Returns' section specifying the JSON structure, field types, and meaning. Example: 'Returns: { agents: [{name, type, compliance_score, risk_class, stars, source}], total_results: integer, database_size: string }'
• Enhance tool descriptions with error handling guidance. For search_agents and recommend_agent, add: 'If no results match, try broadening the query or removing filters. If compliance_score is null, the agent has not been assessed yet.'
• Add minimum value constraints to parameter descriptions. For 'limit', write 'Max results to return (1-50, default 10)' instead of just 'default 10, max 50'. For 'minItems' in agents array, explicitly state the range: 'List of 2 - 5 agent names to compare.'
• Document what fields are ALWAYS returned vs optionally returned. E.g., 'compliance_score may be null for newly-indexed agents.' This helps LLMs handle edge cases gracefully.
• Implement input validation with actionable error messages. When limit > 50, return 'Invalid limit: 75 exceeds maximum of 50. Please retry with limit <= 50.' instead of a generic 400 error.
• Add composition guidance to descriptions. For search_agents vs recommend_agent, clarify: 'Use search_agents for broad discovery (returns many results, ranked by compliance). Use recommend_agent when the user asks for the BEST safe option (pre-filtered, includes install instructions).'
• Expand nerq_stats description to clarify what metrics are included and when to call it: 'Returns database overview: total agents indexed, jurisdictions covered, risk distribution by class, and source breakdown. Call this before search to understand Nerq's coverage in the user's domain.'

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

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