prom-mcp demonstrates solid fundamentals: all 11 tools have clear verb-noun naming (run_query, list_metrics, fetch_alerts) and descriptions (avg ~60 chars). Input schemas are present with typed parameters and descriptions. However, output schemas are not documented in the visible code, parameter descriptions lack format/constraint details (e.g., RFC3339 format for time params is mentioned but not formalized), and error handling guidance is minimal. No tool annotations (readOnlyHint) despite all being read-only. Composition is strong, tools are single-responsibility and chainable (e.g., list_metrics → run_query). Security is good: no secrets in params, rate limiting present. Naming follows verb_noun convention consistently.

• Document output schemas for all tools. Example: run_query returns {result_type: 'matrix'|'vector'|'scalar', data: [{metric: {}, values: [[timestamp, value]]}]}. This enables LLMs to extract and chain results.
• Add format constraints to time parameters. Use JSON Schema pattern or description: 'RFC3339 format (e.g., 2024-01-15T10:30:00Z) or relative (e.g., 5m, 1h, 7d)'. Prevents ambiguous date parsing.
• Implement tool annotations in tool registration. Mark all tools with readOnlyHint: true to signal safety and enable client-side optimizations.
• Enhance error messages with recovery guidance. Example: 'Invalid PromQL: syntax error at position 42. Try: (1) simplify the expression, (2) check metric names with list_metrics, (3) validate syntax with a PromQL parser.'
• Add pagination to list_metrics and list_labels. Include limit (default 50, max 500) and offset parameters. Return total_count so LLMs know if more results exist.

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

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