The Grafana MCP server has well-structured SQL tools with generally good descriptions and complete input schemas. All 4 tools follow verb_noun naming conventions (list_*, describe_*, query_*). Descriptions are action-oriented and explain prerequisites and use cases. Input schemas are present with type definitions. However, there are notable gaps: output schemas are not explicitly documented in the provided source code, error handling guidance is absent from tool descriptions, and parameter descriptions lack format constraints and validation rules that would help LLMs avoid invalid inputs. The tools are read-only (no destructive operations), which simplifies error handling requirements but reduces the need for confirmation patterns. Tool annotations (readOnlyHint) are present via the Features flag, supporting current protocol patterns.

• Document the output schema for each tool as a JSON Schema block or structured table. For query_sql, specify the structure of each row and the types of columns. For list_sql_tables, document the fields in each table object (name, schema, row_count, created_at, etc.). This allows LLMs to reliably extract and use response data.
• Add explicit constraints to parameters: 'limit: integer, range 1 - 10000, default 100', 'start/end: ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) or relative format (now-1h, now-7d)', 'datasource_uid: string, UUID format, required.' Include these in parameter descriptions, not just type definitions.
• Enhance tool descriptions with dependency hints and error recovery: 'If datasource_uid is unknown, use Grafana's UI or call list_datasources (if available). If the table is not found, call list_sql_tables first to confirm the name and schema.'
• Unify parameter naming or add explicit guidance: Create a parameter 'datasource_type' enum (clickhouse, snowflake, athena, mysql, postgresql, mssql) so LLMs know upfront which optional parameters apply. Or rename 'catalog' to 'catalog_or_database' and explain its role per datasource.
• Add pagination to list_sql_databases and list_sql_tables: Introduce 'offset' (default 0) and 'limit' (default 50, max 1000) parameters. Ensure responses include 'total_count' and 'has_more' fields so LLMs can fetch all results without guessing.
• Document common error scenarios and recovery paths in tool descriptions: 'If the query fails with a timeout, the datasource may be overloaded. Wait and retry, or simplify the query. If authentication fails, verify the datasource credentials in Grafana.'

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

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