Prometheus MCP demonstrates solid definition quality with well-structured tool definitions, comprehensive parameter schemas, and actionable descriptions. All 8 tools are explicitly registered with detailed input schemas using Pydantic models. Most tools include response_format enum parameters enabling format choice. Error handling is production-grade with context-aware messages. However, output schemas are not explicitly documented in the code, and some parameter descriptions could be more concise and LLM-optimized (several exceed recommended 200 char length). Tool naming follows verb_noun convention appropriately. No critical security issues detected for this read-only API-focused server.

• Add explicit output schema documentation to all tools. Define a response model (e.g., QueryResult, QueryRangeResult) with typed fields and descriptions. This enables LLMs to understand what data they will receive and how to extract relevant fields for downstream operations.
• Add tool annotations to all 8 tools in the FastMCP registration. Set readOnlyHint=true for all (no state-changing operations). This makes it explicit to clients that these are safe to call without confirmation and improves UI rendering in MCP clients.
• Condense parameter descriptions to 50-200 characters. Focus on WHAT the parameter does and any critical constraints. Move examples and workarounds to a help text or separate documentation section if needed. Example: query_range 'step' could be 'Time-series resolution step (e.g., 1m, 5m, 1h). Use larger steps for longer time ranges to avoid huge responses.'
• Return structured error responses with error_code, error_message, and recovery_hint fields instead of plain strings. This enables clients to categorize errors (retryable, user-fixable, fatal) and present recovery guidance programmatically.
• Add a 'pagination' capability to list_metrics: support offset/limit parameters explicitly and return a 'total_count' field. Currently, 'limit' is present but no offset/cursor mechanism; pagination is essential for discovering metrics in large deployments.
• Document the markdown and json response structures for each tool. Create a separate section in README or schema comments describing the field names, types, and meanings. Example: query markdown response format is a formatted table; json format is [{metric, values: [{timestamp, value}]}]. Make this explicit in tool definitions.