Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The MCP Grafana server defines 43 tools covering Grafana's monitoring, alerting, and incident management APIs. While tool names follow verb_noun conventions and basic schemas are present, there are systematic gaps in parameter descriptions, output schema documentation, and error recovery guidance. Many parameters lack detailed format constraints or usage context. The server reads from test files (test-all-tools.js, test/test-mcp-tools.js) rather than from production source code, suggesting tool definitions may be inferred rather than directly visible in the main codebase.
Output schemas not documented in tool definitions. Tool entries provide only name, description, and input parameters; they do not declare what fields the response contains or how to chain results to downstream tools.
Parameter descriptions lack format constraints and usage guidance. Examples: 'query_prometheus' accepts a 'timeRange' object but does not specify its structure (start, end, format); 'update_dashboard' accepts 'updates' object with no schema. LLMs cannot construct valid payloads without explicit format details.
Add explicit output schema documentation to every tool. For each tool, document the response structure: field names, types, and which fields are required vs optional. Example for 'get_dashboard_by_uid': '{ id: number, uid: string, title: string, panels: Panel[], tags: string[] }'.
Expand parameter descriptions with format constraints, allowed values, and examples. For 'timeRange', specify: 'ISO 8601 object with keys from and to (e.g., { "from": "2024-01-01T00:00:00Z", "to": "2024-01-02T00:00:00Z" })' rather than just 'Time range for the query'.
Add error recovery guidance to every tool description. Include a sentence like 'If the dashboard is not found, call search_dashboards() with a partial title to locate it.' This helps LLMs handle failures gracefully.
Implement pagination for list_* and search_* tools. Add 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters; return a 'total_count' or 'next_cursor' field so agents can fetch large result sets incrementally.
Document pagination and result limits in tool descriptions. State: 'Returns up to 50 results. Use offset parameter to fetch additional items.' This prevents LLMs from assuming they have the complete result set.
Add confirmation or dry-run support for write tools. For 'update_dashboard' and 'create_incident', offer a 'dry_run' boolean parameter that returns what would happen without committing changes. Alternatively, document that agents should call a related 'get_*' tool to verify preconditions.
Standardize datasource identification across tools. Provide a 'get_datasource_by_name' or 'search_datasources' tool that returns the correct UID for a given datasource name, preventing type mismatches (e.g., passing Loki UID to Prometheus query).
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool definitions inferred from test files rather than directly visible in source code. Actual tool registration, schema validation, and error handling must be verified in src/cli.ts or similar entry point.
No error recovery guidance in tool descriptions. Many tools (e.g., 'get_dashboard_by_uid', 'get_incident') do not document what error conditions may occur or what the LLM should do if a resource is not found (e.g., 'Try search_dashboards() with a partial name').
Write operations lack confirmation or dry-run mechanisms. Tools like 'create_incident', 'update_dashboard', and 'add_activity_to_incident' can modify or create records but provide no confirmation step. Agents can make unintended changes without a safety net.
No pagination or result limit guidance. Tools returning lists (e.g., 'list_incidents', 'list_alert_rules', 'search_dashboards') do not document maximum result counts or pagination tokens. LLMs may request unbounded result sets, exhausting context and overwhelming downstream processing.
Vague parameter names and descriptions in multi-datasource tools. 'datasourceUid' is used across Prometheus, Loki, and Pyroscope tools but no guidance on how to discover the correct UID or handle mismatches (e.g., passing a Loki UID to a Prometheus tool).
Missing type definitions for complex parameters. 'timeRange' is used in query_prometheus, query_loki_logs, find_error_pattern_logs, and fetch_pyroscope_profile but is documented only as 'Time range for the query' without specifying expected fields (e.g., 'from', 'to', 'unit').
Verify tool registration in main source code (src/cli.ts or src/server.ts). Ensure tools are registered with complete schemas and descriptions, not inferred from test files. Provide static tool definitions that can be validated at build time.
Add descriptive error messages to tool responses. When a resource is not found, include alternatives. Example: 'Dashboard "prod-overview" not found. Available dashboards: prod-metrics, prod-logs, prod-traces.' This enables LLMs to suggest corrections without extra lookups.
Document permission requirements for each tool. Add a note to 'create_incident', 'update_dashboard', and similar write tools specifying required API permissions (e.g., 'Requires Grafana admin role or write:dashboards scope'). This guides agent configuration and auditability.
Add type hints or enum constraints for string parameters that accept a fixed set of values. For 'resourceType' in 'generate_deeplink', specify: 'One of: dashboard, alert, incident, metric' as an enum rather than a free-form string.
Validate input parameters early and return actionable errors. If 'query_prometheus' receives an invalid PromQL query, respond with 'Invalid PromQL syntax: expected metric name, got EOF. Example: up{job="prometheus"}' rather than a generic 400 error.