---
canonical_url: "https://docs.composio.dev/toolkits/grafana_cloud_mcp"
markdown_url: "https://docs.composio.dev/toolkits/grafana_cloud_mcp.md"
product: "platform"
version: null
last_updated: null
---

# Grafana Cloud MCP

Grafana Cloud MCP lets agents query metrics, logs, traces, dashboards, datasources, alerts, incidents, and related observability resources in an authorized Grafana Cloud stack.

- **Category:** model context protocol
- **Auth:** DCR_OAUTH
- **Composio-managed OAuth available?** No
- **Tools:** 118
- **Triggers:** 0
- **Slug:** `GRAFANA_CLOUD_MCP`
- **Version:** 20260924_00

## Tools

### Add activity to incident

**Slug:** `GRAFANA_CLOUD_MCP_ADD_ACTIVITY_TO_INCIDENT`

Add a note (userNote activity) to an existing incident's timeline using its ID. The note body can include URLs which will be attached as context. Use this to add context to an incident.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `body` | string | Yes | The body of the activity. URLs will be parsed and attached as context |
| `eventTime` | string | No | The time that the activity occurred. If not provided, the current time will be used |
| `incidentId` | string | Yes | The ID of the incident to add the activity to |

### Agento11y manage agents

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_AGENTS`

Read the agent catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): which agents send telemetry, what their system prompts and tools are, how their prompt versions evolved, and how each version scored.

The catalog is derived from ingested telemetry, not from a registration step: an agent exists here once its generations have been seen. It answers "what is this agent" while agento11y_manage_conversations and agento11y_manage_generations answer "what did it do".

Operations:
- 'list': agents in this tenant, newest activity first. Each row carries the latest effective version, first and latest seen times, generation and version counts, tool count, a system prompt prefix, and token_estimate. Paginated via limit and cursor
- 'get': one agent version in full: the complete system prompt, every tool with its JSON schema, and the models it ran on. Returns the latest version unless 'version' is set
- 'list_versions': the version history of one agent, one row per effective version with its seen window, generation count, tool count, and token_estimate. Paginated
- 'list_version_scores': evaluation score aggregates per version, with per-evaluator score_key, pass and fail counts, and mean_score. Use it to compare how versions scored

Versions: an effective version is always 'sha256:<64 lowercase hex>', and only that form is accepted by 'get'; a declared version such as '1.4.2' is reported in the declared_version fields but cannot be looked up. The plugin derives the effective version from the first of these the telemetry carries: the version the SDK reported, a hash of the declared version, a hash of the system prompt. Adding, removing, or editing a tool never mints a new version. Editing the prompt mints one only for an agent that reports neither its own effective version nor a declared version, so an agent that declares '1.4.2' keeps one effective version across prompt edits.

Response size: 'get' returns the whole system prompt plus every tool schema, which can be tens of thousands of tokens. Check token_estimate.total from 'list' or 'list_versions' before fetching, and prefer the system_prompt_prefix in those rows when a prefix is enough.

Cross-referencing: pass an agent name from 'list' to agento11y_manage_conversations as the search filter agent = "<name>" to find what that agent actually did.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. For 'list', also repeat the same name_prefix, start_time, and end_time using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d re-resolves and is rejected.

Permissions: every operation is a read and needs grafana-agento11y-app.data:read (Agento11y Editor or Admin). This tool performs no writes.

When to use:
- Discovering which agent names exist before filtering conversations or generations by agent
- Reading the system prompt or tool inventory an agent ran with, or how they changed between versions
- Checking whether a new prompt version scores worse than the previous one

When NOT to use:
- Reading individual conversations, generations, or their scores (use agento11y_manage_conversations and agento11y_manage_generations)
- Inspecting evaluators or the rules that schedule them (use agento11y_manage_evaluators and agento11y_manage_eval_rules)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results per page (default 50, capped at 200 by the API) (for 'list' and 'list_versions') |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor, echoed back exactly (for 'list' and 'list_versions'). For 'list' also resend the same name_prefix, start_time, and end_time as the first call using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d drifts between calls and is rejected. |
| `version` | string | No | Effective version 'sha256:<64 lowercase hex>' from 'list' or 'list_versions', accepted only by 'get'. Omit it for the latest version. Declared versions such as '1.4.2' are not accepted here; they are reported in the declared_version fields. |
| `end_time` | string | No | End of the time range in RFC3339 or relative format (e.g. now). For 'list' it keeps agents last seen at or before this time and defaults to no upper bound. For 'list_version_scores' it ends the score window; passing it without start_time gives a 90-day window ending here. |
| `operation` | string ("list" | "get" | "list_versions" | "list_version_scores") | Yes | The operation to perform: 'list' for the agent catalog, 'get' for one agent version in full (system prompt, tools, models), 'list_versions' for the version history of one agent, 'list_version_scores' for evaluation score aggregates per version |
| `agent_name` | string | No | Agent name from 'list'. Required for 'get', 'list_versions', and 'list_version_scores'. An explicitly empty string selects the unnamed agent (telemetry with no agent name), which 'get' and 'list_versions' accept and 'list_version_scores' rejects. |
| `start_time` | string | No | Start of the time range in RFC3339 or relative format (e.g. now-7d). For 'list' it keeps agents last seen at or after this time and defaults to no lower bound. For 'list_version_scores' it starts the score window; omitting it does not mean no lower bound, because the API then either scopes to the agent's 50 most recent versions or falls back to a 90-day window. |
| `name_prefix` | string | No | Agent name filter (for 'list'). Despite the parameter name, the API matches it case-insensitively anywhere in the name, so 'agent' also returns 'my-agent'. |

### Agento11y manage conversations

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_CONVERSATIONS`

List, search, and fetch LLM conversations from Grafana Agent Observability (the grafana-agento11y-app plugin).

Operations:
- 'list': recent conversations (lightweight; id, title, generation count, timestamps), paginated via limit and cursor
- 'search': search conversations by filter expression and time range; results include models, agents, error counts, rating and eval summaries, and trace IDs
- 'get': one conversation by ID with all its generations, including full prompts and outputs (can be large)

Filter syntax for 'search': key operator value, with the value in double quotes; multiple filters are separated by spaces and combined with AND.
Filter keys (trace): model, provider, agent, agent.version, status, error.type, error.category, duration, tool.name, operation, namespace, cluster, service
Filter keys (metadata): generation_count, eval.passed, eval.evaluator_id, eval.score_key, eval.score
Operators: =, !=, >, <, >=, <=, =~ (regex)
Example: status = "error" agent = "claude-code"

Pagination: when a response has next_cursor, fetch the next page by calling the same operation again with cursor set to next_cursor. For 'search', also repeat the same filters, start_time, and end_time as the first call, using absolute RFC3339 times; relative ranges like now-24h shift between calls and the cursor will be rejected.

When to use:
- Debugging an AI application: find failing or low-rated conversations, then inspect their generations
- Reviewing evaluation results and user ratings across conversations

When NOT to use:
- Fetching a single generation or its evaluation scores (use agento11y_manage_generations)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results per page (default 50) (for 'list' and 'search' operations) |
| `cursor` | string | No | Pagination cursor from a previous response (for 'list' and 'search' operations). To fetch the next page set this to next_cursor. For 'search' also resend the same filters and start_time/end_time from the first call and use absolute RFC3339 times; relative ranges like now-24h invalidate the cursor. |
| `filters` | string | No | Filter expression (for 'search' operation). Format: key operator value with the value in double quotes, multiple filters separated by spaces. See the tool description for keys and operators. |
| `end_time` | string | No | End of the search time range in RFC3339 or relative format (e.g. now). Defaults to now (for 'search' operation) |
| `operation` | string ("list" | "search" | "get") | Yes | The operation to perform: 'list' for recent conversations, 'search' to filter conversations by expression and time range, 'get' to fetch one conversation with all its generations by ID |
| `start_time` | string | No | Start of the search time range in RFC3339 or relative format (e.g. now-6h). Defaults to now-24h (for 'search' operation) |
| `conversation_id` | string | No | The conversation ID (required for 'get' operation) |

### Agento11y manage eval collections

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_EVAL_COLLECTIONS`

Manage the curated conversations of Grafana Agent Observability (the grafana-agento11y-app plugin): bookmark conversations as saved conversations and group them into collections.

Two linked resources:
- A saved conversation (/eval/saved-conversations) is a bookmark on one conversation, keyed by a saved_id you choose. It gives that conversation a stable ID, a name, and tags a collection can reference. It does not preserve the conversation: retention deletes the bookmark and its collection memberships together with the conversation it points at.
- A collection (/eval/collections) is a named group of saved conversations, used as the source material for offline evaluation. Collections hold saved conversations, never raw conversation IDs, so a conversation must already be bookmarked before a collection accepts it.

Operations:
- 'list_saved_conversations': bookmarked conversations in this tenant, filterable by source ('telemetry' for bookmarked production traffic, 'manual' for hand-built ones). Also reports total_count for the whole filtered set, not just the page
- 'get_saved_conversation': one bookmark by ID
- 'list_collections_for_saved_conversation': the collections one bookmark belongs to (unpaginated)
- 'list_collections': collections in this tenant, each with its member_count
- 'get_collection': one collection by ID
- 'list_collection_members': the saved conversations in a collection
- 'save_conversation': bookmark a live conversation by conversation_id. saved_id is optional and defaults to 'saved-<conversation_id>'; a conversation can only be saved once, so a repeat returns 409 naming the existing saved_id
- 'delete_saved_conversation': delete a bookmark by saved_id. Idempotent, and it also removes the bookmark from every collection it belonged to, with no separate membership cleanup. On a source='manual' bookmark the backend goes further and deletes the underlying conversation and its generations, so the content itself is gone
- 'create_collection': create an empty collection from a name and optional description. The response carries the server-assigned collection_id needed by the membership operations
- 'update_collection': patch a collection's name or description. Omitted fields are left unchanged, and an explicitly empty description clears it
- 'delete_collection': delete a collection and its memberships in one transaction. Idempotent, and the saved conversations themselves are kept
- 'add_collection_members': add saved_ids to a collection. Every ID must already be a saved conversation (a missing one returns 400 naming it), and re-adding an existing member is a no-op
- 'remove_collection_member': drop one saved conversation from a collection. Idempotent, and the bookmark itself is kept

Identifiers: saved_id is caller-chosen and accepts letters, digits, '_', '.', ':', and '-' (looser than the evaluator and rule IDs, which reject hyphens). collection_id is a UUID assigned by the server when a collection is created; it cannot be chosen.

List rows are already enriched: every saved conversation in 'list_saved_conversations' and 'list_collection_members' embeds the collections it belongs to plus generation_count, total_tokens, agent_names, models, model_providers, and tags. Read those fields instead of calling 'list_collections_for_saved_conversation' per row, which is one request per result. An absent collections field means the row was not enriched; an empty array means the row genuinely belongs to no collection.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Echo the value back exactly; never construct or increment one. 'list_saved_conversations' returns an opaque numeric value while 'list_collections' and 'list_collection_members' return the last row ID, so a cursor from one operation passed to another fails or silently skips rows. Keep the same source filter across pages.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Reading what is already curated: which collections exist, how large they are, and what is in them
- Turning a triaged failure into a regression collection: 'save_conversation', then 'create_collection' or 'add_collection_members'
- Bookmarking a conversation found via agento11y_manage_conversations so a collection can reference it by a stable ID
- Collection hygiene: renaming a collection, or removing a conversation that no longer belongs in it

When NOT to use:
- Searching or reading live conversations and generations (use agento11y_manage_conversations and agento11y_manage_generations)
- Inspecting evaluators or the rules that schedule them (use agento11y_manage_evaluators and agento11y_manage_eval_rules)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Human-readable name. Required for 'save_conversation' and 'create_collection'; optional for 'update_collection', where an omitted name is left unchanged and a blank one is rejected. |
| `tags` | object | No | Optional string tags to store on a bookmark (for 'save_conversation') |
| `limit` | integer | No | Maximum number of results per page (default 50, max 500) (for the paginated list operations) |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented. A cursor belongs to the operation and filters that produced it: 'list_saved_conversations' returns an opaque numeric value while 'list_collections' and 'list_collection_members' return the last row ID, so they are not interchangeable. |
| `source` | string ("telemetry" | "manual") | No | Saved conversation source filter: 'telemetry' for bookmarked production conversations, 'manual' for hand-built ones (for 'list_saved_conversations') |
| `saved_id` | string | No | Saved conversation ID. Required for 'get_saved_conversation', 'list_collections_for_saved_conversation', 'delete_saved_conversation', and 'remove_collection_member'. Optional for 'save_conversation', which derives 'saved-<conversation_id>' when it is omitted. Only letters, digits, '_', '.', ':', and '-' are accepted. |
| `operation` | string ("list_saved_conversations" | "get_saved_conversation" | "list_collections_for_saved_conversation" | "list_collections" | "get_collection" | "list_collection_members" | "save_conversation" | "delete_saved_conversation" | "create_collection" | "update_collection" | "delete_collection" | "add_collection_members" | "remove_collection_member") | Yes | The operation to perform. Reads: 'list_saved_conversations', 'get_saved_conversation', 'list_collections_for_saved_conversation', 'list_collections', 'get_collection', 'list_collection_members'. Writes: 'save_conversation' (bookmark a conversation), 'delete_saved_conversation', 'create_collection', 'update_collection' (PATCH, partial), 'delete_collection', 'add_collection_members', 'remove_collection_member' |
| `saved_ids` | array | No | Saved conversation IDs to add to a collection (required, non-empty, for 'add_collection_members'; rejected by 'create_collection', which always creates an empty collection). Every ID must already be a saved conversation; bookmark it with 'save_conversation' first. Re-adding a member is a no-op. |
| `description` | string | No | Collection description (for 'create_collection' and 'update_collection'). On 'update_collection' an omitted description is left unchanged and an explicitly empty string clears it. |
| `collection_id` | string | No | Collection ID. Required for 'get_collection', 'list_collection_members', 'update_collection', 'delete_collection', 'add_collection_members', and 'remove_collection_member'. Rejected by 'create_collection' (the API assigns a UUID) and by 'save_conversation' (bookmarking cannot also add to a collection). |
| `conversation_id` | string | No | Conversation to bookmark (required for 'save_conversation'). Find one with agento11y_manage_conversations. |

### Agento11y manage eval rules

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_EVAL_RULES`

Manage the evaluation rules and guards of Grafana Agent Observability (the grafana-agento11y-app plugin): the configuration that decides when evaluators run.

Two different resources with different runtime behavior:
- Eval rules (/eval/rules) are asynchronous. A rule selects production traffic (selector, match filters, sample_rate) and schedules its evaluator_ids to score matching generations after the fact. Rules only observe; they never change a request.
- Guards (/eval/hook-rules; there is no /eval/guards path) run inline on the request path and can deny it, redact content, or block tool calls. A guard is inert until the agent application calls the hooks endpoint (POST /eval/hooks:evaluate) itself: a stored guard on its own changes nothing.

Operations:
- 'list_rules': asynchronous eval rules in this tenant (paginated)
- 'get_rule': one eval rule by ID
- 'list_guards': guards, read from /eval/hook-rules (paginated)
- 'get_guard': one guard by ID
- 'create_rule': create an asynchronous eval rule from an inline 'definition'
- 'update_rule': patch an existing rule; send only the fields to change (rule_id is taken from the 'rule_id' parameter and must not appear in the definition)
- 'delete_rule': delete a rule by ID
- 'preview_rule': dry-run a selector, match, and sample_rate against recent traffic and return how many generations would match and be sampled, plus example generations. Run this before creating a rule that spends judge tokens
- 'create_guard': create an inline guard (stored as a hook rule)
- 'update_guard': full replace of a guard (PUT, not PATCH) — omitted fields reset to server defaults, so send the complete definition, normally a 'get_guard' result with your edits applied
- 'delete_guard': delete a guard by ID

Identifiers (rule_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Rule selectors: user_visible_turn, all_assistant_generations, tool_call_steps, errored_generations, conversation (guards also accept 'all'). Match keys are arrays and include agent_name, agent_version, operation_name, model.provider, model.name, mode, error.type, error.category, and tags.<key>. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'preview_rule' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- A score names an evaluator and you need to know which rule scheduled it and on what traffic
- Auditing which guards are live and whether they warn or deny
- Binding a new evaluator to production traffic with 'create_rule', after checking the blast radius with 'preview_rule'
- Adding a guard, or promoting one from warn to deny after watching its false-positive rate

When NOT to use:
- Inspecting what an evaluator checks, or the template it came from (use agento11y_manage_evaluators)
- Listing conversations, generations, or scores (use agento11y_manage_conversations and agento11y_manage_generations)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results per page (default 50, max 500) (for 'list_rules' and 'list_guards') |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor (for 'list_rules' and 'list_guards') |
| `rule_id` | string | No | Eval rule ID (for the '_rule' operations) or guard ID (for the '_guard' operations). Required for 'get_rule', 'update_rule', 'delete_rule', 'get_guard', 'update_guard', and 'delete_guard'; for 'create_rule', 'create_guard', and 'preview_rule' the ID comes from 'definition'. |
| `operation` | string ("list_rules" | "get_rule" | "list_guards" | "get_guard" | "create_rule" | "update_rule" | "delete_rule" | "preview_rule" | "create_guard" | "update_guard" | "delete_guard") | Yes | The operation to perform. Reads: 'list_rules', 'get_rule', 'list_guards', 'get_guard'. Writes: 'create_rule', 'update_rule' (PATCH, partial), 'delete_rule', 'preview_rule' (dry-run a selector and match against recent traffic, stores nothing), 'create_guard', 'update_guard' (PUT, full replace), 'delete_guard' |
| `definition` | object | No | Request body for the create/update/preview operations. Eval rules ('create_rule', 'update_rule'): rule_id (string, required on create, only letters/digits/underscore/dot), enabled (bool), selector (user_visible_turn&#124;all_assistant_generations&#124;tool_call_steps&#124;errored_generations&#124;conversation), match (object of string arrays, e.g. {"agent_name": ["my-agent"]}), sample_rate (0-1), evaluator_ids (array, the evaluators must already exist), alert_rule_uids (array), min_idle_seconds (int, required when selector is 'conversation': the idle period after which a conversation counts as finished; with that selector sample_rate applies per conversation, not per generation). 'update_rule' is a PATCH: send only the fields to change and do NOT include rule_id, which the API rejects as an unknown field - it is taken from the rule_id parameter. 'preview_rule': selector, match, sample_rate, and optionally rule_id. Guards ('create_guard', 'update_guard'): rule_id (required on create; on update it must match the rule_id parameter), enabled (bool), phase (preflight&#124;postflight, default preflight), priority (int, lower runs first), selector (as above, plus 'all'), match (as above), action_on_fail (warn&#124;deny - start with warn, which records the outcome without blocking the request, and promote to deny only after watching the false-positive rate), short_circuit (bool), and exactly ONE decision shape: evaluator_ids (an evaluator decides), redact ({patterns: [{id, regex}]} - each entry is exactly id and regex, a 'replacement' key returns 400, and the placeholder is derived from id) or tool_filter ({blocked_names: [glob]}). 'update_guard' is a PUT full replace: fields you omit reset to server defaults, so send a complete definition (normally a 'get_guard' result with your edits). |

### Agento11y manage evaluators

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_EVALUATORS`

Manage the evaluator catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): read evaluators, evaluator templates, and the judge model catalog, and create, test, or delete evaluators.

An evaluator is a scoring function (kind: llm_judge, json_schema, regex, or heuristic) that scores generations. The scores returned by agento11y_manage_generations operation 'scores' name the evaluator that produced them. Templates are versioned starting points for evaluators. Judge providers and models are the LLM backends an llm_judge evaluator can use.

Operations:
- 'list_evaluators': evaluators in this tenant (paginated)
- 'get_evaluator': one evaluator by ID, with its kind, config, and output_keys
- 'list_templates': evaluator templates, filterable by scope ('global' for built-ins, 'tenant' for locally created ones)
- 'get_template': one template with its config, output_keys, and version list
- 'list_template_versions': version history of a template, each version with its config and output_keys
- 'list_judge_providers': judge providers configured on this stack
- 'list_judge_models': judge models, optionally filtered by provider
- 'upsert_evaluator': create or update an evaluator from an inline 'definition'. POST is create-or-update keyed on definition.evaluator_id; there is no separate update operation, and re-using an existing 'version' returns 409, so bump the version to change an evaluator
- 'delete_evaluator': soft-delete an evaluator by ID. Rules and guards that reference it keep the reference and silently stop producing scores, so check agento11y_manage_eval_rules first
- 'fork_template': derive a new evaluator from a template in one call. Prefer this over copying 'get_template' output into 'upsert_evaluator', which the API rejects
- 'test_evaluator': run an inline evaluator definition against one generation and return its scores without persisting anything. Useful for tuning a judge config before 'upsert_evaluator'

Identifiers (evaluator_id, template_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Template operations need a stack with the evaluator template store configured and return 404 otherwise. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'test_evaluator' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- A score from agento11y_manage_generations names an evaluator and you need to see what it checks
- Inspecting a template before deriving an evaluator from it
- Tuning an llm_judge config against a real generation with 'test_evaluator' before storing it
- Creating an evaluator so a rule or guard can reference it

When NOT to use:
- Finding which rule scheduled an evaluator, or which guard enforces it (use agento11y_manage_eval_rules)
- Listing conversations, generations, or scores (use agento11y_manage_conversations and agento11y_manage_generations)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results per page (default 50, max 500) (for the paginated list operations) |
| `scope` | string ("global" | "tenant") | No | Template scope filter: 'global' for built-in templates, 'tenant' for templates created in this tenant (for 'list_templates') |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor (for the paginated list operations) |
| `provider` | string | No | Judge provider ID to filter models by, e.g. 'openai' (for 'list_judge_models') |
| `operation` | string ("list_evaluators" | "get_evaluator" | "list_templates" | "get_template" | "list_template_versions" | "list_judge_providers" | "list_judge_models" | "upsert_evaluator" | "delete_evaluator" | "fork_template" | "test_evaluator") | Yes | The operation to perform. Reads: 'list_evaluators', 'get_evaluator', 'list_templates', 'get_template', 'list_template_versions', 'list_judge_providers', 'list_judge_models'. Writes: 'upsert_evaluator' (create or update from 'definition'), 'delete_evaluator', 'fork_template' (derive an evaluator from a template), 'test_evaluator' (score one generation with an inline definition without storing it) |
| `definition` | object | No | Request body for 'upsert_evaluator', 'fork_template', and 'test_evaluator'. For 'upsert_evaluator': evaluator_id (string, required, only letters/digits/underscore/dot - hyphens are rejected), version (string, required - re-using an existing version returns HTTP 409, so bump it to change an evaluator), kind (llm_judge&#124;json_schema&#124;regex&#124;heuristic), description (string), config (object, shape depends on kind), output_keys (array of {key, type, description, unit, pass_threshold, enum, min, max, pass_match, pass_value}). The evaluator ID lives in this body, not in a URL or the evaluator_id parameter. For 'fork_template': evaluator_id (required) plus optional version (which template version to fork, defaults to the template's latest), config, and output_keys overrides. For 'test_evaluator': kind, config, and output_keys of the evaluator to try - the API rejects evaluator_id and version here, and nothing is persisted. |
| `template_id` | string | No | Template ID (required for 'get_template', 'list_template_versions', and 'fork_template') |
| `evaluator_id` | string | No | Evaluator ID (required for 'get_evaluator' and 'delete_evaluator'). For 'upsert_evaluator' and 'fork_template' the evaluator ID belongs in 'definition' instead, because the API reads it from the request body. |
| `generation_id` | string | No | Generation to score (required for 'test_evaluator'). Find one with agento11y_manage_conversations. |

### Agento11y manage experiments

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_EXPERIMENTS`

Manage the offline experiments of Grafana Agent Observability (the grafana-agento11y-app plugin), their trials, and their scores.

An experiment is one offline run of an agent over a test suite. Each test case in the suite produces one or more trials, each trial is scored by the experiment's evaluators, and the experiment reports a pass rate. Experiments are created by SDK runners, not from here.

Operations:
- 'list': experiments in this tenant, filterable by suite_id, status, source, created_by, tag, and a created_at or completed_at window. Each row carries the same result summary as 'get', so finding the experiment that regressed needs no second call
- 'get': one experiment with its result summary: pass rate, average final score, total cost and tokens
- 'get_report': the per-test-case breakdown, trimmed by row_limit. The test case input and expected values, the score records, and the artifact records are dropped because those fields have no size bound; each trial keeps its error message, a score_count, an artifact_count, and the IDs the drill-downs take
- 'list_trials': one experiment's trials, paginated. Prefer this over 'get_report' on a large suite. It reports no cost or token counts: only the report path fills those in
- 'list_scores': every score in one experiment, paginated
- 'get_trial': one trial in full, including the test case snapshot with its input and expected values
- 'list_trial_scores': one trial's scores, with the explanation each judge wrote
- 'list_trial_artifacts': one trial's artifact metadata, with a content_ref rather than the bytes
- 'list_facets': the distinct suites, owners, and tags across every experiment in the tenant, for building a 'list' filter. Only source, from, and to narrow it; it rejects a filter it would otherwise have to ignore
- 'update': patch an experiment's name, description, tags, or metadata. Only the experiment's created_by may patch it, so patching an experiment someone else started answers 401
- 'cancel': stop a running experiment. It checks no owner, so any caller with the write permission can stop any experiment. An experiment that already finished is left alone: the call answers 200 and returns it unchanged instead of failing, so read the status on the result rather than assume a run was stopped

Size: 'get_report' is fetched whole before it is trimmed, and a response above 10 MiB fails the call rather than arriving truncated.

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it, repeating the first page's filters with absolute RFC3339 times. A relative bound such as now-7d re-resolves between calls and moves the window the cursor was issued against, so it is rejected alongside a cursor.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Both writes need grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Finding the last experiment for a suite after a suspected regression: 'list' by suite_id, then read the pass rate off the row
- Finding which test cases an experiment failed on, then reading one failing trial in full
- Labelling an experiment after triage, so 'list' by tag finds it later
- Stopping an experiment that is burning judge tokens on a broken candidate

When NOT to use:
- Reading scores on live production traffic (use agento11y_manage_generations and agento11y_manage_conversations)
- Inspecting the test cases a suite defines, or editing them (use agento11y_manage_test_suites)
- Inspecting what an evaluator checks (use agento11y_manage_evaluators)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | No | End of the created_at window in RFC3339 or relative format (e.g. now), for 'list' and 'list_facets' |
| `tag` | array | No | Experiment tag filter (for 'list'). Several tags match an experiment carrying any of them, not all of them. |
| `from` | string | No | Start of the created_at window in RFC3339 or relative format (e.g. now-7d), for 'list' and 'list_facets' |
| `name` | string | No | New experiment name (for 'update'). An omitted field is left unchanged, and a blank name is rejected. A finished experiment accepts only description and tags, so renaming one returns 409. |
| `tags` | array | No | Replacement tag list for 'update'. It overwrites the whole list rather than adding to it, so run 'get' first and send the existing tags plus the new ones; an explicitly empty array clears them. The tag filter for 'list' is the separate 'tag' parameter. |
| `limit` | integer | No | Maximum number of results per page (default 50, max 500) (for the paginated list operations) |
| `order` | string ("created_at_desc" | "completed_at_desc") | No | Sort order for 'list', newest first either way. Defaults to 'created_at_desc'. 'completed_at_desc' returns a single page and cannot be combined with a cursor. |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented. Repeat the same filters as the first call, using absolute RFC3339 times. |
| `source` | string ("collection" | "external") | No | Experiment origin filter: 'collection' for runs built from a saved collection, 'external' for runs reported by an SDK runner (for 'list' and 'list_facets') |
| `status` | string ("running" | "completed" | "failed" | "canceled") | No | Experiment status filter (for 'list'). A finished run is 'completed'; there is no 'succeeded' status. |
| `metadata` | object | No | Replacement metadata object (for 'update'). A finished experiment rejects it with 409. |
| `suite_id` | string | No | Test suite ID filter (for 'list') |
| `trial_id` | string | No | Trial ID from 'list_trials' or 'get_report' (required for 'get_trial', 'list_trial_scores', and 'list_trial_artifacts') |
| `operation` | string ("list" | "get" | "get_report" | "list_trials" | "list_scores" | "get_trial" | "list_trial_scores" | "list_trial_artifacts" | "list_facets" | "update" | "cancel") | Yes | The operation to perform. Reads: 'list', 'get', 'get_report', 'list_trials', 'list_scores', 'get_trial', 'list_trial_scores', 'list_trial_artifacts', 'list_facets'. Writes: 'update' (PATCH the name, description, tags, or metadata of an experiment), 'cancel' (stop a running experiment) |
| `row_limit` | integer | No | Maximum number of test case rows 'get_report' returns (default 50, max 500). The report route is not paginated, so this trims the returned rows and sets rows_truncated; it does not reduce what the plugin sends. |
| `created_by` | string | No | Owner filter, matched against the values 'list_facets' reports under owners (for 'list') |
| `description` | string | No | New experiment description (for 'update'). An omitted field is left unchanged and an explicitly empty string clears it. |
| `completed_to` | string | No | End of the completed_at window in RFC3339 or relative format (for 'list') |
| `experiment_id` | string | No | Experiment ID from 'list'. Required for 'get', 'get_report', 'list_trials', 'list_scores', 'update', and 'cancel'. |
| `completed_from` | string | No | Start of the completed_at window in RFC3339 or relative format (for 'list'). 'from' and 'to' filter created_at; this pair filters completed_at instead, so it drops runs that have not finished. |

### Agento11y manage generations

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_GENERATIONS`

Fetch a single LLM generation and its evaluation scores from Grafana Agent Observability (the grafana-agento11y-app plugin).

Operations:
- 'get': full generation detail by ID, including prompt, output, model, and usage (can be large)
- 'scores': evaluation scores for a generation (evaluator, score key, score type, value, passed, explanation)

When to use:
- Drilling into one generation found via agento11y_manage_conversations
- Checking why an evaluation passed or failed for a specific generation

When NOT to use:
- Searching or listing conversations (use agento11y_manage_conversations)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of scores per page (default 50) (for 'scores' operation) |
| `cursor` | string | No | Pagination cursor from a previous response (for 'scores' operation) |
| `operation` | string ("get" | "scores") | Yes | The operation to perform: 'get' for the full generation detail, 'scores' for the evaluation scores of the generation |
| `generation_id` | string | Yes | The generation ID |

### Agento11y manage test suites

**Slug:** `GRAFANA_CLOUD_MCP_AGENTO11Y_MANAGE_TEST_SUITES`

Manage the test suites of Grafana Agent Observability (the grafana-agento11y-app plugin), their versions, and their test cases.

A test suite is the input side of an offline experiment: a named set of test cases that an SDK runner replays against an agent. Suites are versioned, and a test case belongs to one version rather than to the suite, so every test case operation takes both suite_id and version.

A version is either a draft or published. A draft accepts test case edits; publishing freezes it and makes it the suite's latest_version, which is the version a runner picks up. A suite has at most one draft at a time.

Operations:
- 'list_suites': the test suites in this tenant, newest first. The rows carry no version history
- 'get_suite': one suite with its full version history under versions
- 'list_test_cases': the test cases of one suite version, oldest first, paginated
- 'get_test_case': one test case in full, with its free-form input and expected values
- 'create_suite': a new empty suite. It has no version yet, so follow it with 'create_draft_version'
- 'update_suite': patch a suite's name, description, or tags
- 'create_draft_version': open a new editable version. A suite that already has a draft answers 409
- 'publish_version': freeze a draft. There is no unpublish; a published version answers 409 to a second publish and to every test case edit, so changing a published suite means a new draft
- 'upsert_test_case': write a whole test case into a draft version. It replaces the stored case rather than merging into it, so a field left out is cleared; read the case with 'get_test_case' first and send it back complete
- 'delete_test_case': remove one test case from a draft version. Deleting a test case that is already gone answers 404

Pagination: when a response carries next_cursor, call the same operation again with cursor set to it.

Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403.

When to use:
- Reading the test cases at the version an experiment used, after it reported a failing case
- Adding a regression case to a suite, then publishing the draft so the next experiment picks it up
- Correcting a test case whose expected value was wrong

When NOT to use:
- Reading how a suite scored, or the trials, scores, and artifacts behind it (use agento11y_manage_experiments)
- Changing what an evaluator checks (use agento11y_manage_evaluators)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Suite name. Required and non-blank for 'create_suite'. For 'update_suite' an omitted name is left unchanged and a blank one is rejected. For 'upsert_test_case' it names the case. |
| `tags` | array | No | Replacement tag list for 'update_suite' and 'upsert_test_case'. It overwrites the whole list rather than adding to it, so read the current tags first; an explicitly empty array clears them. |
| `input` | object | No | What the case feeds the agent (required and non-empty for 'upsert_test_case'). The shape is free-form and decided by the runner, so copy an existing case of the suite before inventing one. |
| `limit` | integer | No | Maximum number of results per page (default 50, max 500) (for the list operations) |
| `cursor` | string | No | Pagination cursor from a previous response's next_cursor, echoed back exactly and never constructed or incremented |
| `version` | string | No | Suite version such as 'v3', taken from the versions list of 'get_suite'. Required for 'publish_version', 'list_test_cases', 'get_test_case', 'upsert_test_case', and 'delete_test_case'. 'create_draft_version' assigns the next version itself, so do not send one. |
| `category` | string | No | Test case category (for 'upsert_test_case') |
| `expected` | object | No | What the case expects back (for 'upsert_test_case'). Free-form, and read by the evaluators rather than compared by the API. |
| `metadata` | object | No | Free-form metadata object (for 'upsert_test_case') |
| `suite_id` | string | No | Test suite ID from 'list_suites'. Required for every operation except 'list_suites', which takes none, and 'create_suite', where it is an optional caller-chosen ID that must not already exist. |
| `changelog` | string | No | Note describing what the new version changes (for 'create_draft_version') |
| `operation` | string ("list_suites" | "get_suite" | "list_test_cases" | "get_test_case" | "create_suite" | "update_suite" | "create_draft_version" | "publish_version" | "upsert_test_case" | "delete_test_case") | Yes | The operation to perform. Reads: 'list_suites', 'get_suite', 'list_test_cases', 'get_test_case'. Writes: 'create_suite', 'update_suite' (PATCH the name, description, or tags), 'create_draft_version' (open an editable version), 'publish_version' (freeze it), 'upsert_test_case' (write a whole case into a draft), 'delete_test_case' |
| `description` | string | No | Suite or test case description. An omitted field is left unchanged by 'update_suite' and an explicitly empty string clears it. |
| `empty_draft` | boolean | No | Start the new version with no test cases (for 'create_draft_version'). The default copies every case of the latest published version, which is what an edit to an existing suite wants. |
| `test_case_id` | string | No | Test case ID. Required for 'get_test_case' and 'delete_test_case'. For 'upsert_test_case' it selects an existing case to replace; omit it to have one created. |
| `artifact_refs` | array | No | Artifacts the case refers to, each an artifact_id with its name and kind (for 'upsert_test_case') |

### Alerting manage routing

**Slug:** `GRAFANA_CLOUD_MCP_ALERTING_MANAGE_ROUTING`

Manage Grafana alerting routing configuration, including notification policies, contact points and time intervals.

Notification policies define how alerts are grouped, routed, and which contact points receive them.
Time intervals define active/mute periods for alert notifications.

When to use:
- Understanding how alerts are routed to contact points/receivers
- Debugging why an alert went to a specific receiver
- Checking grouping, timing, or mute interval settings

When NOT to use:
- Checking alert rule configuration or state (use alerting_manage_rules)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Filter contact points by name (exact match). Only used with get_contact_points. |
| `limit` | integer | No | The maximum number of results to return. Default is 100. Only used with get_contact_points. |
| `operation` | string ("get_notification_policies" | "get_contact_points" | "get_contact_point" | "get_time_intervals" | "get_time_interval") | Yes | The operation to perform: 'get_notification_policies' to retrieve the notification policy tree, 'get_contact_points' to list all contact points, 'get_contact_point' to get a specific contact point by name, 'get_time_intervals' to list all time intervals, 'get_time_interval' to get a specific time interval by name |
| `datasource_uid` | string | No | Optional: UID of an Alertmanager-compatible datasource to query for receivers. If omitted, returns Grafana-managed contact points. Only used with get_contact_points. |
| `time_interval_name` | string | No | Name of the time interval to retrieve (required for get_time_interval operation) |
| `contact_point_title` | string | No | Title of the contact point to retrieve (required for get_contact_point operation) |

### Alerting manage rules

**Slug:** `GRAFANA_CLOUD_MCP_ALERTING_MANAGE_RULES`

Manage Grafana alert rules with full CRUD capabilities and filtering.

When to use:
- Understanding why an alert is or isn't firing
- Auditing alert rule configuration (queries, conditions, labels, notification settings)
- Finding alert rules by state, folder, group, or name
- Creating, updating, or deleting alert rules
- Comparing rule versions to see what changed

When NOT to use:
- Checking how alerts are routed to receivers (use alerting_manage_routing)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `for` | string | No | Duration before alert fires, e.g. '5m' (required for 'create', 'update') |
| `data` | array | No | Array of alert query objects (required for 'create'/'update'). Each object has: datasourceUid (string, required), model (object with expr for data queries or type/expression/conditions for expressions), refId (string, auto-assigned if omitted), relativeTimeRange ({from, to} in seconds, defaults to {from:600,to:0}). For server-side expressions use datasourceUid '__expr__'. Example: [{datasourceUid: 'prometheus', model: {expr: 'up == 0'}}, {datasourceUid: '__expr__', model: {type: 'threshold', expression: 'A', conditions: [{evaluator: {type: 'gt', params: [0]}}]}}] |
| `title` | string | No | The title of the alert rule (required for 'create', 'update') |
| `labels` | object | No | Optional labels for the alert rule |
| `org_id` | integer | No | The organization ID (required for 'create', 'update') |
| `record` | object | No | Recording rule config. Fields: from (string, required - ref ID e.g. 'A'), metric (string, required - metric name), targetDatasourceUid (string, optional). |
| `states` | array | No | Filter by alert state: firing, pending, normal, recovering, nodata, error (for 'list' operation) |
| `matchers` | array | No | Label matchers to filter alert instances. Each string is a Prometheus-style matcher e.g. 'severity="critical"', 'env!="dev"', 'team=~"backend.*"'. Requires Grafana 12.4+. |
| `rule_uid` | string | No | The UID of the alert rule (required for 'get', 'versions', 'update', 'delete'; optional for 'create') |
| `condition` | string | No | The query condition identifier, e.g. 'A', 'B' (required for 'create', 'update') |
| `is_paused` | boolean | No | If true, the alert rule remains inactive, Default is false |
| `operation` | string ("list" | "get" | "versions" | "create" | "update" | "delete") | Yes | The operation to perform: 'list', 'get', 'versions', 'create', 'update', or 'delete'. To create a rule, use operation 'create' and provide all required fields in a single call. To update a rule, first use 'get' to retrieve its full configuration, then 'update' with all required fields plus your changes. |
| `rule_type` | string ("alerting" | "recording") | No | Filter by rule type (for 'list' operation) |
| `folder_uid` | string | No | The folder UID. For 'list': filter by exact folder UID (mutually exclusive with search_folder). For 'create'/'update': the folder to store the rule in (required). |
| `rule_group` | string | No | The rule group name (required for 'create', 'update') |
| `rule_limit` | integer | No | Maximum number of rules to return (default 200, max 200). Requires Grafana 12.4+ (for 'list' operation) |
| `annotations` | object | No | Optional annotations for the alert rule |
| `limit_alerts` | integer | No | Limit alert instances per rule. For list: 0 omits alerts. For get: <=0 defaults to 200. Max 200. |
| `no_data_state` | string | No | State when no data: NoData, Alerting, OK (required for 'create', 'update') |
| `search_folder` | string | No | Search folders by path using partial matching (for 'list' operation). Requires Grafana 12.4+. Mutually exclusive with folder_uid. |
| `datasource_uid` | string | No | Optional: UID of a Prometheus or Loki datasource to query for datasource-managed alert rules (for 'list' operation) |
| `exec_err_state` | string | No | State on execution error: NoData, Alerting, OK (required for 'create', 'update') |
| `keep_firing_for` | string | No | Enables continous firing of alert for specified time even when condition is no longer met. Default is 0 (resolves immediately) |
| `label_selectors` | array | No | Prometheus-style selectors to filter alert rules by labels. Each string is a selector e.g. '{severity="critical", team=~"backend.*"}'. All selectors must match (AND). |
| `search_rule_name` | string | No | Search alert rule names/titles using partial matching. Requires Grafana 12.4+ (for 'list' operation) |
| `disable_provenance` | boolean | No | If true, the alert remains editable in the Grafana UI (sets X-Disable-Provenance header). Defaults to true. |
| `notification_settings` | object | No | Notification settings object. Fields: receiver (string, required), groupBy ([]string), groupWait/groupInterval/repeatInterval (duration strings), muteTimeIntervals/activeTimeIntervals ([]string). |
| `missing_series_evals_to_resolve` | integer | No | Consecutive evaluation intervals with no data required to mark the alert as resolved. Default is 2. |

### Alerting manage silences

**Slug:** `GRAFANA_CLOUD_MCP_ALERTING_MANAGE_SILENCES`

Manage Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers, without changing the alert rules themselves.

Operations:
- 'list': list existing silences. Optionally filter by rule_uid (matches the __alert_rule_uid__ label) or by matchers.
- 'get': retrieve a single silence by silence_id.
- 'create': create a new silence. Requires matchers, starts_at, ends_at (RFC3339) and comment.
- 'update': modify an existing silence by silence_id. Requires matchers, starts_at, ends_at and comment. The id is only kept when the posted matchers and starts_at match the stored ones, so pass back the starts_at returned by 'get'; otherwise Alertmanager expires the old silence and returns a new id.
- 'delete': expire/remove a silence by silence_id.

When to use:
- Muting noisy or expected alerts during maintenance windows
- Inspecting or cleaning up existing silences

When NOT to use:
- Changing alert rule configuration or state (use alerting_manage_rules)
- Changing how alerts are routed to receivers (use alerting_manage_routing)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `comment` | string | No | A human-readable comment explaining the silence (required for 'create' and 'update') |
| `ends_at` | string | No | Silence end time in RFC3339 format, e.g. '2026-07-11T12:00:00Z' (required for 'create' and 'update') |
| `matchers` | array | No | Label matchers. Required (at least one) for 'create' and 'update'. For 'list', used as an optional filter. |
| `rule_uid` | string | No | Optional: filter listed silences to those scoped to this alert rule UID (matches the __alert_rule_uid__ label). Only used with 'list'. |
| `operation` | string ("list" | "get" | "create" | "update" | "delete") | Yes | The operation to perform: 'list' to list silences, 'get' to retrieve a silence by id, 'create' to create a new silence, 'update' to modify an existing silence by id, 'delete' to expire a silence by id |
| `starts_at` | string | No | Silence start time in RFC3339 format, e.g. '2026-07-11T10:00:00Z' (required for 'create' and 'update'). Grafana clamps a start time in the past to the moment of creation, so for 'update' pass back the starts_at returned by 'get' to keep the silence id stable. |
| `created_by` | string | No | Author of the silence. Defaults to 'grafana-assistant'. |
| `silence_id` | string | No | The silence id (required for 'get', 'update' and 'delete') |

### Analyze loki labels

**Slug:** `GRAFANA_CLOUD_MCP_ANALYZE_LOKI_LABELS`

Audits a Loki label strategy and optionally diagnoses query performance. Returns per-label verdicts, missing base labels, normalisation issues, and a recommended set. Pass datasourceUid for live cardinality or labels for static scoring; both may be combined.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | array | No | Caller-supplied labels (static mode). |
| `selector` | string | No | Optional LogQL selector for stats / perf diagnosis. |
| `maxLabels` | integer | No |  |
| `endRfc3339` | string | No |  |
| `perfMetrics` | object | No | Runtime metrics; presence triggers perf diagnosis. |
| `startRfc3339` | string | No |  |
| `datasourceUid` | string | No | Datasource UID (live mode). |
| `expectedBaseLabels` | array | No |  |

### Ask assistant

**Slug:** `GRAFANA_CLOUD_MCP_ASK_ASSISTANT`

Send a message to Grafana Assistant and wait for the full text reply. The assistant may use tools, metrics, logs, and other stack context—broader than firing one isolated data-source query.

Use for open-ended questions, triage, or anything that needs assistant reasoning and tool use, in addition to the more targeted MCP tools.

**Multi-turn:** pass contextId from a previous ask_assistant result to continue the same conversation.

**Time:** complex tasks can take several minutes; the call blocks until the reply is done or the request times out. Consider running this tool as a background task if able.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | The question or instruction to send to Grafana Assistant (natural language). |
| `contextId` | string | No | Optional. Context ID from a previous ask_assistant response to continue the same conversation. |

### Check datasources health

**Slug:** `GRAFANA_CLOUD_MCP_CHECK_DATASOURCES_HEALTH`

Check datasource health. Filter by type or UIDs; omit both to check all.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | No | Plugin type filter; omit to check all |
| `uids` | array | No | UIDs to check |
| `offset` | integer | No | Number to skip for pagination |

### Create annotation

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_ANNOTATION`

Create a new annotation on a dashboard or panel. Set format to 'graphite' and provide 'what' for Graphite-format annotations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | object | No | Optional JSON payload |
| `tags` | array | No | Optional list of tags |
| `text` | string | No | Annotation text (required unless format is graphite) |
| `time` | integer | No | Start time epoch ms |
| `what` | string | No | Annotation text for Graphite format (required when format is graphite) |
| `when` | integer | No | Epoch ms timestamp for Graphite format |
| `format` | string ("graphite") | No | Set to 'graphite' to create a Graphite-format annotation |
| `panelId` | integer | No | Panel ID |
| `timeEnd` | integer | No | End time epoch ms |
| `dashboardUid` | string | No | Dashboard UID |
| `graphiteData` | string | No | Optional string payload for Graphite format |

### Create datasource

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_DATASOURCE`

Create a datasource. If type is ambiguous, call search_plugin_information first; install the plugin if needed. IMPORTANT: always call this tool twice. First call: provide only the type — the tool returns a field schema. After receiving the schema, you MUST ask the user for every required field value explicitly; do not infer or use defaults without user confirmation. Second call: provide the type, the display name in the top-level name argument, schemaReviewed=true, and the fields map populated with values confirmed by the user. Never handle credentials — remind the user to rotate any detected. Returns UID, health check, and a config page link. 

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | Datasource base URL when required by the plugin |
| `name` | string | Yes | Datasource display name |
| `type` | string | Yes | Grafana datasource plugin type, for example prometheus |
| `access` | string | No | How Grafana should access the datasource (proxy or direct) |
| `fields` | object | No | Datasource field values to provision, keyed by field key from the schema returned on the first call. The server uses each field's target (root or jsonData) to place values correctly in the YAML. Example: {"url": "http://prometheus:9090", "httpMethod": "POST"}. |
| `database` | string | No | Optional database name |
| `basicAuth` | boolean | No | Whether Grafana should use basic auth |
| `isDefault` | boolean | No | Whether this should become the default datasource |
| `schemaReviewed` | boolean | No | Set to true on the second call to confirm you reviewed the schema and collected values from the user. |
| `withCredentials` | boolean | No | Whether Grafana should forward credentials such as cookies |

### Create folder

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_FOLDER`

Create a Grafana folder. Provide a title and optional UID. Returns the created folder.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | No | Optional folder UID. If omitted, Grafana will generate one. |
| `title` | string | Yes | The title of the folder. |
| `parentUid` | string | No | Optional parent folder UID. If set, the folder will be created under this parent. |

### Create incident

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_INCIDENT`

Create a new Grafana incident. Requires title, severity, and room prefix. Allows setting status and labels. This tool should be used judiciously and sparingly, and only after confirmation from the user, as it may notify or alarm lots of people.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | The title of the incident |
| `labels` | array | No | The labels to add to the incident |
| `status` | string | No | The status of the incident |
| `isDrill` | boolean | No | Whether the incident is a drill incident |
| `severity` | string | Yes | The severity of the incident |
| `attachUrl` | string | No | The URL of the attachment |
| `roomPrefix` | string | Yes | The prefix of the room to create the incident in |
| `attachCaption` | string | No | The caption of the attachment |

### Create investigation

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_INVESTIGATION`

Start a Grafana Assistant investigation: an agentic, multi-step root-cause analysis across the stack's metrics, logs, traces, dashboards, and alerts.

Provide a natural-language instruction describing what to investigate. Optionally set a title, share with teams via teamNames, or pick an agent profile via agentProfileId.

The investigation runs asynchronously: this returns investigationId and chatId immediately; poll get_investigation for lifecycle state and results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | No | Optional. Short human-readable title for the investigation. Generated from the instruction when omitted. |
| `teamNames` | array | No | Optional. Grafana team names to share the investigation with. The caller must be a member of each team. |
| `instruction` | string | Yes | What to investigate, in natural language. Include the symptom, affected service/resource, and time range when known. |
| `agentProfileId` | string | No | Optional. Agent profile ID to run the investigation with (see list_investigation_profiles). Uses the default profile when omitted. |

### Create snapshot

**Slug:** `GRAFANA_CLOUD_MCP_CREATE_SNAPSHOT`

Create a Grafana snapshot from a full dashboard payload. Supports optional expiration and external snapshot fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | No | Custom snapshot key. Required when external is true |
| `name` | string | No | Optional snapshot name |
| `expires` | integer | No | Snapshot expiration in seconds (e.g. 3600 for 1 hour) |
| `external` | boolean | No | Store snapshot on external server. Requires key and deleteKey when true |
| `dashboard` | object | Yes | Complete dashboard model to snapshot (as returned by Grafana dashboard APIs) |
| `deleteKey` | string | No | Secret key for deleting external snapshots. Required when external is true |

### Delete snapshot

**Slug:** `GRAFANA_CLOUD_MCP_DELETE_SNAPSHOT`

Delete a Grafana snapshot by snapshot key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Snapshot key to delete |

### Describe athena table

**Slug:** `GRAFANA_CLOUD_MCP_DESCRIBE_ATHENA_TABLE`

Get column names for an Athena table. Use after list_athena_tables. NEXT: Use query_athena with discovered column names.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `table` | string | Yes | Table name to describe. |
| `region` | string | No | AWS region override. Defaults to datasource config. |
| `catalog` | string | No | Data catalog name. Defaults to datasource config. |
| `database` | string | No | Database name. Defaults to datasource config. |
| `datasourceUid` | string | Yes | The UID of the Athena datasource. |

### Describe clickhouse table

**Slug:** `GRAFANA_CLOUD_MCP_DESCRIBE_CLICKHOUSE_TABLE`

Get column schema for a ClickHouse table. Pass the database from list_clickhouse_tables results. NEXT: Use query_clickhouse with discovered column names.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `table` | string | Yes | Table name to describe |
| `database` | string | No | Database name (defaults to 'default') |
| `datasourceUid` | string | Yes | The UID of the ClickHouse datasource |

### Describe infrastructure

**Slug:** `GRAFANA_CLOUD_MCP_DESCRIBE_INFRASTRUCTURE`

Start here when users ask about their infrastructure, services, or architecture. Returns pre-built summaries of service groups including topology, metrics, deployment, dependencies, and datasource UIDs.

Infrastructure memories are generated by scanning Prometheus metric datasources to discover services, then using AI to summarize each service group. Memories are organized by service group (e.g. "Payment System", "Inventory"). Each group has chunks covering: overview, metrics, deployment, dependencies, logs, and — when code search finds relevant repos — a code & repositories chunk describing the source repos, languages, and deployment/configuration evidence found in the code. Results also include datasource UIDs for metrics (Prometheus), logs (Loki), and traces (Tempo) — use these to query the right datasource in follow-up tool calls. Individual services/components (e.g. "cortex-gw") are listed inside their parent group's overview chunk — use the exact component name in keywords to find the right group.

Uses hybrid search (semanticQuery for meaning + keywords for lexical matching). keywords is critical for finding specific sub-components within groups.

Batch queries: pass an array of queries (max 3) to explore multiple service groups or angles in a single call. Results from all queries are merged and deduplicated by group name, so overlapping matches won't be returned twice. Prefer batching related angles over multiple sequential calls.

IMPORTANT: semanticQuery must be a single short question with the group/component name — e.g. "What metrics does checkout-service expose?". Do NOT append generic terms like "architecture, components, dependencies, telemetry" — these match every document. keywords must use the exact service/component name (e.g. "cortex-gw").

Examples:
- User asks "What's my infrastructure like?" → queries: [{semanticQuery: "What services are running?", keywords: "service"}]
- User asks "Tell me about the checkout system" → queries: [{semanticQuery: "How does checkout-service work?", keywords: "checkout-service"}]
- User asks "Compare the checkout and payment systems" → queries: [{semanticQuery: "How does checkout-service work?", keywords: "checkout-service"}, {semanticQuery: "How does payment-service work?", keywords: "payment-service"}]
Each query returns full groups with overview, metrics, dependencies, logs, datasource UIDs, and (when available) code/repo information — enough to start investigating with targeted queries.

Required: queries (each entry needs semanticQuery and keywords)
Optional: datasourceUID (pass if a datasource UID is known from the conversation, user query, or previous tool results)

When to use:
- User asks broad questions about their infrastructure or what services are running
- User asks about specific services or components
- Need topology, relationships, or configuration
- Need to discover which datasources (metrics, logs, traces) to query for a service
- Before querying raw metrics or logs — check here first to find the right datasource UIDs
- Need to know which repository or source code backs a service (when code evidence is available)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `queries` | array | Yes | One or more search queries, each with semanticQuery + keywords. Use multiple queries (max 3) to explore different service groups or angles in a single call. Results are merged and deduplicated by group name. A single well-targeted query is usually enough. |
| `datasourceUID` | string | No | Filter results to a specific metric datasource. Pass if the user mentions a datasource, if one was returned by a previous tool (e.g., dashboard panels, query results), or if the conversation references a specific datasource UID. |

### Describe snowflake table

**Slug:** `GRAFANA_CLOUD_MCP_DESCRIBE_SNOWFLAKE_TABLE`

Get column schema for a Snowflake table. Pass the database/schema from list_snowflake_tables results. NEXT: Use query_snowflake with discovered column names.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `table` | string | Yes | Table name to describe |
| `schema` | string | No | Schema name (defaults to 'PUBLIC') |
| `database` | string | No | Database name (defaults to the datasource's configured database) |
| `datasourceUid` | string | Yes | The UID of the Snowflake datasource |

### Generate deeplink

**Slug:** `GRAFANA_CLOUD_MCP_GENERATE_DEEPLINK`

Generate deeplink URLs for Grafana resources. Supports dashboards (requires dashboardUid or provisioningPreview), panels (requires dashboardUid or provisioningPreview, plus panelId), and Explore queries (requires datasourceUid and optionally queries). For dashboard and panel links, provisioningPreview points at a dashboard staged on a provisioning repository branch (e.g. a git-sync PR preview). For explore links, the time range and queries are embedded inside the Grafana explore state. Set shorten=true to also attempt a /goto/<uid> short URL; if shortening fails, the full deeplink is returned.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `panelId` | integer | No | Panel ID (required for panel type) |
| `queries` | array | No | List of query objects for explore links (e.g. [{"refId":"A","expr":"up"}]) |
| `shorten` | boolean | No | If true, try to shorten the generated URL to /goto/<uid>. If shortening fails, return the original deeplink. |
| `timeRange` | object | No | Time range for the link |
| `queryParams` | object | No | Additional URL query parameters (for dashboard/panel types) |
| `dashboardUid` | string | No | Dashboard UID (for stored dashboards). Mutually exclusive with provisioningPreview for dashboard and panel types. |
| `resourceType` | string | Yes | Type of resource: dashboard, panel, or explore |
| `datasourceUid` | string | No | Datasource UID (required for explore type) |
| `provisioningPreview` | object | No | Identifies a dashboard staged on a provisioning repository branch (e.g. a git-sync PR preview). Mutually exclusive with dashboardUid for dashboard and panel types. |

### Get alert group

**Slug:** `GRAFANA_CLOUD_MCP_GET_ALERT_GROUP`

Get a specific alert group from Grafana OnCall by its ID. Returns the full alert group details, including the most recent alert and its raw payload when the OnCall API provides them. Alert payloads carry integration-specific fingerprints (for example Sentry's payload.data.event.hashes or Alertmanager's payload.alerts[].fingerprint) that identify recurring alerts across different alert groups.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `alertGroupId` | string | Yes | The ID of the alert group to retrieve |

### Get annotations

**Slug:** `GRAFANA_CLOUD_MCP_GET_ANNOTATIONS`

Fetch Grafana annotations using filters such as dashboard UID, time range and tags.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Epoch ms end time |
| `from` | integer | No | Epoch ms start time |
| `tags` | array | No | Filter by tags. Multiple tags allowed; use matchAny to control AND/OR logic |
| `type` | string | No | annotation or alert |
| `limit` | integer | No | Max results default 100 |
| `userId` | integer | No | Filter by creator user ID |
| `panelId` | integer | No | Filter by panel ID |
| `alertUid` | string | No | Filter by alert UID |
| `matchAny` | boolean | No | If true, match any tag (OR). If false, match all tags (AND). Default: false |
| `dashboardUid` | string | No | Filter by dashboard UID |

### Get annotation tags

**Slug:** `GRAFANA_CLOUD_MCP_GET_ANNOTATION_TAGS`

Returns annotation tags with optional filtering by tag name. Only the provided filters are applied.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | No | Optional filter by tag name |
| `limit` | string | No | Max results, default 100 |

### Get assertions

**Slug:** `GRAFANA_CLOUD_MCP_GET_ASSERTIONS`

Get assertion summary for a given entity with its type, name, env, site, namespace, and a time range

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `env` | string | No | The env of the entity to list |
| `site` | string | No | The site of the entity to list |
| `endTime` | string | Yes | The end time in RFC3339 format (e.g. 2024-01-01T00:00:00Z) or relative format (e.g. now) |
| `namespace` | string | No | The namespace of the entity to list |
| `startTime` | string | Yes | The start time in RFC3339 format (e.g. 2024-01-01T00:00:00Z) or relative format (e.g. now-1h) |
| `entityName` | string | No | The name of the entity to list |
| `entityType` | string | No | The type of the entity to list (e.g. Service, Node, Pod, etc.) |

### Get current oncall users

**Slug:** `GRAFANA_CLOUD_MCP_GET_CURRENT_ONCALL_USERS`

Get the list of users currently on-call for a specific Grafana OnCall schedule ID. Returns the schedule ID, name, and a list of detailed user objects for those currently on call.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scheduleId` | string | Yes | The ID of the schedule to get current on-call users for |

### Get dashboard by uid

**Slug:** `GRAFANA_CLOUD_MCP_GET_DASHBOARD_BY_UID`

Retrieves the complete dashboard, including panels, variables, and settings, for a specific dashboard identified by its UID. The response includes 'apiVersion' and 'isV2': when 'isV2' is true the dashboard uses the v2 schema (panels live under 'elements' keyed by name, arranged by 'layout'; variables under 'variables'), otherwise it is classic v1 ('panels[]' with 'templating.list'). WARNING: Large dashboards can consume significant context window space. Consider using get_dashboard_summary for overview or get_dashboard_property for specific data instead.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | Yes | The UID of the dashboard |

### Get dashboard panel queries

**Slug:** `GRAFANA_CLOUD_MCP_GET_DASHBOARD_PANEL_QUERIES`

Retrieve panel queries from a Grafana dashboard. Supports all datasource types (Prometheus, Loki, CloudWatch, SQL, etc.) and row-nested panels. Optionally filter to a specific panel by ID with `panelId`. Optionally provide `variables` for template variable substitution, which populates `processedQuery` and `requiredVariables` fields. Returns an array of objects with fields: title, query (raw expression), datasource (object with uid and type), and optionally processedQuery, refId, and requiredVariables.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | Yes | The UID of the dashboard |
| `panelId` | integer | No | Optional panel ID to filter to a specific panel |
| `variables` | object | No | Optional variable substitutions (e.g., {"job": "api-server"}) |

### Get dashboard property

**Slug:** `GRAFANA_CLOUD_MCP_GET_DASHBOARD_PROPERTY`

Get specific parts of a dashboard using JSONPath expressions to minimize context window usage. JSONPath targets the dashboard's native schema. Classic v1 paths: '$.title' (title)\, '$.panels[*].title' (all panel titles)\, '$.panels[0]' (first panel)\, '$.templating.list' (variables)\, '$.annotations.list' (saved dashboard annotation queries/definitions)\, '$.tags' (tags)\, '$.panels[*].targets[*].expr' (all queries). v2 dashboards (see isV2 from get_dashboard_by_uid) use different paths: '$.title'\, '$.elements' (panels\, keyed by name)\, '$.variables' (variables)\, '$.annotations'. Use this instead of get_dashboard_by_uid when you only need specific dashboard properties.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | Yes | The UID of the dashboard |
| `jsonPath` | string | Yes | JSONPath expression to extract specific data (e.g., '$.panels[0].title' for first panel title, '$.panels[*].title' for all panel titles, '$.templating.list' for variables, '$.annotations.list' for saved dashboard annotation queries/definitions) |

### Get dashboard summary

**Slug:** `GRAFANA_CLOUD_MCP_GET_DASHBOARD_SUMMARY`

Get a compact summary of a dashboard including title\, panel count\, panel types\, variables\, and other metadata without the full JSON. Use this for dashboard overview and planning modifications without consuming large context windows.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | Yes | The UID of the dashboard |

### Get datasource

**Slug:** `GRAFANA_CLOUD_MCP_GET_DATASOURCE`

Retrieves detailed information about a specific datasource by UID or name. Returns the full datasource model, including name, type, URL, access settings, JSON data, and secure JSON field status. Provide either uid or name; uid takes priority if both are given.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | No | The UID of the datasource. If provided, takes priority over name. |
| `name` | string | No | The name of the datasource. Used if UID is not provided. |

### Get incident

**Slug:** `GRAFANA_CLOUD_MCP_GET_INCIDENT`

Get a single incident by ID. Returns the full incident details including title, status, severity, labels, timestamps, and other metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The ID of the incident to retrieve |

### Get investigation

**Slug:** `GRAFANA_CLOUD_MCP_GET_INVESTIGATION`

Get one Grafana Assistant investigation (AI-driven root-cause investigation) by ID.

Returns the investigation's identifiers (investigationId and chatId), the authoritative row lifecycle state and metadata (title, description, state, summary, labels, team ownership, timestamps, completion quality, failure details), and the engine work snapshot (sessionStatus, mode, epoch, plan, report content).

The row's state field is authoritative for investigation lifecycle (pending, in_progress, completed, failed, cancelled, paused). The snapshot's sessionStatus only describes the engine session (idle, active, pause) — do not infer completion or failure from it. Legacy (v1) investigations may have no snapshot; the row metadata is still returned with snapshotError set.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `investigationId` | string | Yes | Investigation ID, as returned by list_investigations or create_investigation. |

### Get investigation thread

**Slug:** `GRAFANA_CLOUD_MCP_GET_INVESTIGATION_THREAD`

Get the working thread of one Grafana Assistant investigation (AI-driven root-cause investigation) by ID: the user-visible conversation between the investigation agent and its tools.

Resolves the investigation to its backing chat and returns the non-hidden user-visible messages in order. Each message keeps only prose (the agent's narrative and findings), tool calls (toolName and toolInput), and tool results (raw query output); internal reasoning and bookkeeping blocks are excluded. Tool results are returned verbatim and can be large — use limit and offset to page through long threads (total reports the full user-visible count).

Use this to inspect the raw data behind a report's [cite:pN] citations: list_investigation_evidence maps each panel ID to a toolUseId, and the tool_result block with that toolUseId in this thread holds the captured query output.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of messages to return. 0 or omitted returns all. |
| `offset` | integer | No | Number of user-visible messages to skip from the start of the thread. |
| `investigationId` | string | Yes | Investigation ID, as returned by list_investigations or create_investigation. |

### Get oncall shift

**Slug:** `GRAFANA_CLOUD_MCP_GET_ONCALL_SHIFT`

Get detailed information for a specific Grafana OnCall shift using its ID. A shift represents a designated time period within a schedule when users are actively on-call. Returns the full shift details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `shiftId` | string | Yes | The ID of the shift to get details for |

### Get panel image

**Slug:** `GRAFANA_CLOUD_MCP_GET_PANEL_IMAGE`

Render a Grafana dashboard panel or full dashboard as a PNG image. Returns the image as base64 encoded data. Requires the Grafana Image Renderer service to be installed. Either dashboardUid (for stored dashboards) or provisioningPreview (for dashboards staged on a provisioning repository branch, e.g. a git-sync PR) must be supplied. Use this for generating visual snapshots of dashboards for reports, alerts, or presentations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `orgId` | integer | No | The Grafana organization ID to render the panel in. Defaults to the default org (usually 1) |
| `scale` | integer | No | Scale factor for the image (1-3). Defaults to 1 |
| `theme` | string | No | Theme for the rendered image: light or dark. Defaults to dark |
| `width` | integer | No | Width of the rendered image in pixels. Defaults to 1000 |
| `height` | integer | No | Height of the rendered image in pixels. Defaults to 500 |
| `panelId` | integer | No | The ID of the panel to render. If omitted, the entire dashboard is rendered |
| `timeout` | integer | No | Rendering timeout in seconds. Defaults to 60 |
| `timeRange` | object | No | Time range for the rendered image |
| `variables` | object | No | Dashboard variables to apply. Values can be a single string or an array of strings for multi-value variables (e.g., {"var-datasource": "prometheus", "var-instance": ["server1", "server2"]}) |
| `dashboardUid` | string | No | The UID of a stored dashboard containing the panel. Required unless provisioningPreview is provided. |
| `provisioningPreview` | object | No | Render a dashboard from a provisioning repository branch (e.g. a git-sync PR preview). Mutually exclusive with dashboardUid. |

### Get plugin

**Slug:** `GRAFANA_CLOUD_MCP_GET_PLUGIN`

Check whether a Grafana plugin is installed and retrieve its details (name, version, type, enabled status). Returns installed=false when the plugin is not found. Use install_plugin when a plugin is not installed to install plugin after confirming this action with the user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pluginId` | string | Yes | The plugin ID to check (e.g. 'prometheus', 'grafana-piechart-panel', 'grafana-oncall-app') |

### Get query examples

**Slug:** `GRAFANA_CLOUD_MCP_GET_QUERY_EXAMPLES`

Get example queries for a specific datasource type. Provides sample queries with descriptions for Prometheus (PromQL), Loki (LogQL), ClickHouse (SQL with Grafana macros), CloudWatch (metric configurations), and InfluxDB (Flux and InfluxQL). Use this to understand query syntax and common patterns for each datasource. TIP: Use list_datasources to find datasource UIDs, or get_datasource if you know the exact name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `datasourceType` | string | Yes | The datasource type to get examples for (e.g. 'prometheus', 'loki', 'clickhouse', 'cloudwatch', 'influxdb') |

### Get resource description

**Slug:** `GRAFANA_CLOUD_MCP_GET_RESOURCE_DESCRIPTION`

List available permissions and assignment capabilities for a Grafana resource type.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resourceType` | string ("dashboards" | "datasources" | "folders" | "teams" | "users" | "serviceaccounts") | Yes | Type of Grafana resource to get description for |

### Get resource permissions

**Slug:** `GRAFANA_CLOUD_MCP_GET_RESOURCE_PERMISSIONS`

List all permissions set on a specific Grafana resource (e.g., dashboard, datasource, folder) by its type and ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource` | string | Yes | Resource type (e.g. 'dashboards' 'datasources' 'folders') |
| `resourceId` | string | Yes | Unique identifier of the resource (UID for dashboards/datasources/folders) |

### Get role assignments

**Slug:** `GRAFANA_CLOUD_MCP_GET_ROLE_ASSIGNMENTS`

List all assignments for a specific role, showing which users, teams, and service accounts have been assigned this role.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `roleUID` | string | Yes | Role UID to retrieve |

### Get role details

**Slug:** `GRAFANA_CLOUD_MCP_GET_ROLE_DETAILS`

Get detailed information about a specific Grafana role by its UID, including permissions, metadata, and configuration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `roleUID` | string | Yes | Role UID to retrieve |

### Get snapshot

**Slug:** `GRAFANA_CLOUD_MCP_GET_SNAPSHOT`

Get a Grafana snapshot by key, including snapshot metadata and dashboard payload.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Snapshot key to retrieve |

### Grafana api request

**Slug:** `GRAFANA_CLOUD_MCP_GRAFANA_API_REQUEST`

Make an authenticated HTTP request to the Grafana API. Similar to 'gh api' for GitHub. Supports any Grafana API endpoint with optional jq-style response filtering. Use this for API endpoints that don't have a dedicated tool.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jq` | string | No | A jq expression to filter or transform the JSON response (e.g. '.dashboards[] &#124; .title'). |
| `body` | string | No | Request body (JSON string). Used with POST, PUT, and PATCH requests. |
| `method` | string ("GET" | "POST" | "PUT" | "PATCH" | "DELETE") | No | HTTP method. Defaults to GET |
| `headers` | object | No | Additional HTTP headers to include in the request. |
| `endpoint` | string | Yes | The API path relative to the Grafana base URL (e.g. '/api/org', '/api/dashboards/uid/abc123'). Must start with '/'. |

### Install plugin

**Slug:** `GRAFANA_CLOUD_MCP_INSTALL_PLUGIN`

Install a Grafana plugin by its plugin ID. If the version is not already confirmed with the user, omit it — the tool will look up the latest version and return it for confirmation before installing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `version` | string | No | The exact version to install. Must be confirmed with the user before calling — if unknown, omit this field to look up the latest version first. |
| `pluginId` | string | Yes | The plugin ID to install (e.g. 'grafana-image-renderer', 'grafana-piechart-panel') |

### List alert groups

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ALERT_GROUPS`

List alert groups from Grafana OnCall with filtering options. Supports filtering by alert group ID, route ID, integration ID, state (new, acknowledged, resolved, silenced), team ID, time range, labels, and name. For time ranges, use format '{start}_{end}' ISO 8601 timestamp range (e.g., '2025-01-19T00:00:00_2025-01-19T23:59:59' for a specific day). For labels, use format 'key:value' (e.g., ['env:prod', 'severity:high']). Returns a list of alert group objects with their details. Supports pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Filter by specific alert group ID |
| `name` | string | No | Filter by alert group name |
| `page` | integer | No | The page number to return |
| `state` | string | No | Filter by alert group state (one of: new, acknowledged, resolved, silenced) |
| `labels` | array | No | Filter by labels in format key:value (e.g., ['env:prod', 'severity:high']) |
| `teamId` | string | No | Filter by team ID |
| `routeId` | string | No | Filter by route ID |
| `startedAt` | string | No | Filter by time range in format '{start}_{end}' ISO 8601 timestamp range (UTC assumed, no timezone indicator needed) (e.g., '2025-01-19T00:00:00_2025-01-19T23:59:59') |
| `integrationId` | string | No | Filter by integration ID |

### List all roles

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ALL_ROLES`

List all roles in Grafana. Optionally filter to show only roles that can be delegated by the current user. Returns role details including UID, name, permissions, and metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `delegatableOnly` | boolean | No | Optional: If set true only return roles that can be delegated by current user |

### List athena catalogs

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ATHENA_CATALOGS`

START HERE for Athena: List available data catalogs (e.g. AwsDataCatalog, Iceberg connectors). NEXT: Use list_athena_databases with a catalog.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | No | AWS region override (e.g. us-east-1). Defaults to datasource config. |
| `datasourceUid` | string | Yes | The UID of the Athena datasource. Use list_datasources to find available UIDs. |

### List athena databases

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ATHENA_DATABASES`

List databases in an Athena catalog. Use after list_athena_catalogs. NEXT: Use list_athena_tables with a database.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | No | AWS region override. Defaults to datasource config. |
| `catalog` | string | No | Data catalog name (e.g. AwsDataCatalog). Defaults to datasource config. |
| `datasourceUid` | string | Yes | The UID of the Athena datasource. |

### List athena tables

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ATHENA_TABLES`

List tables in an Athena database. Use after list_athena_databases. NEXT: Use describe_athena_table to see column schemas before querying.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | No | AWS region override. Defaults to datasource config. |
| `catalog` | string | No | Data catalog name. Defaults to datasource config. |
| `database` | string | No | Database name. Defaults to datasource config. |
| `datasourceUid` | string | Yes | The UID of the Athena datasource. |

### List clickhouse tables

**Slug:** `GRAFANA_CLOUD_MCP_LIST_CLICKHOUSE_TABLES`

START HERE for ClickHouse: List available tables (name, database, engine, row count, size). NEXT: Use describe_clickhouse_table to see column schemas.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | No | Database name to filter tables (lists all non-system databases if not specified) |
| `datasourceUid` | string | Yes | The UID of the ClickHouse datasource |

### List cloudwatch dimensions

**Slug:** `GRAFANA_CLOUD_MCP_LIST_CLOUDWATCH_DIMENSIONS`

List dimension keys for a CloudWatch metric. Requires region. Supports cross-account monitoring via optional accountId parameter. Use after list_cloudwatch_metrics. NEXT: Use query_cloudwatch with discovered dimensions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | Yes | AWS region (e.g. us-east-1) |
| `accountId` | string | No | AWS account ID for cross-account monitoring. Specify an account ID to filter dimensions from a specific source account, or 'all' for all linked accounts. |
| `namespace` | string | Yes | CloudWatch namespace (e.g. AWS/ECS) |
| `metricName` | string | Yes | Metric name (e.g. CPUUtilization) |
| `datasourceUid` | string | Yes | The UID of the CloudWatch datasource |

### List cloudwatch metrics

**Slug:** `GRAFANA_CLOUD_MCP_LIST_CLOUDWATCH_METRICS`

List metrics for a CloudWatch namespace. Requires region. Supports cross-account monitoring via optional accountId parameter. Use after list_cloudwatch_namespaces. NEXT: Use list_cloudwatch_dimensions\, then query_cloudwatch.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | Yes | AWS region (e.g. us-east-1) |
| `accountId` | string | No | AWS account ID for cross-account monitoring. Specify an account ID to filter metrics from a specific source account, or 'all' for all linked accounts. |
| `namespace` | string | Yes | CloudWatch namespace (e.g. AWS/ECS, AWS/EC2) |
| `datasourceUid` | string | Yes | The UID of the CloudWatch datasource |

### List cloudwatch namespaces

**Slug:** `GRAFANA_CLOUD_MCP_LIST_CLOUDWATCH_NAMESPACES`

START HERE for CloudWatch: List available namespaces (AWS/EC2, AWS/ECS, AWS/RDS, etc.). Requires region. Supports cross-account monitoring via optional accountId parameter. NEXT: Use list_cloudwatch_metrics with a namespace.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `region` | string | Yes | AWS region (e.g. us-east-1) |
| `accountId` | string | No | AWS account ID for cross-account monitoring. Specify an account ID to filter namespaces from a specific source account, or 'all' for all linked accounts. |
| `datasourceUid` | string | Yes | The UID of the CloudWatch datasource |

### List datasources

**Slug:** `GRAFANA_CLOUD_MCP_LIST_DATASOURCES`

List all configured datasources in Grafana. Use this to discover available datasources and their UIDs. Supports filtering by type and/or name (case-insensitive substring match) and pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Case-insensitive substring match on the datasource name. For example, 'prod' matches datasources named 'prometheus-prod-eu' and 'loki-prod-us'. Useful on instances with many datasources where filtering by type alone returns too many results. |
| `type` | string | No | The type of datasources to search for. For example, 'prometheus', 'loki', 'tempo', etc... |
| `limit` | integer | No | Maximum number of datasources to return (max 100) |
| `offset` | integer | No | Number of datasources to skip for pagination |

### List graphite metrics

**Slug:** `GRAFANA_CLOUD_MCP_LIST_GRAPHITE_METRICS`

Discover available metric paths in a Graphite datasource by browsing the metric tree. Returns nodes matching the query pattern\, each indicating whether it is a leaf metric (has data) or an expandable branch (has children). Use '*' as a wildcard at any level to enumerate the tree (e.g. '*' → top-level nodes\, 'servers.*' → all second-level nodes under 'servers'). Drill down progressively to find the full metric path before querying with query_graphite.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Metric path pattern to search. Use '*' as a wildcard at any level (e.g. '*' lists top-level nodes, 'servers.*' lists all servers, 'servers.web01.*' lists all metrics under web01). |
| `datasourceUid` | string | Yes | The UID of the Graphite datasource to query |

### List graphite tags

**Slug:** `GRAFANA_CLOUD_MCP_LIST_GRAPHITE_TAGS`

List available tag names in a Graphite datasource that uses tag-based metrics. Returns a list of tag name strings (e.g. ["name"\, "env"\, "region"]). These tags can be used to build tag-based target expressions for query_graphite (e.g. seriesByTag('name=cpu.load\,env=prod')). Optionally filter by a prefix. Requires Graphite to be configured with tag support.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prefix` | string | No | Optional prefix to filter tag names (e.g. 'env' returns tags whose name starts with 'env'). |
| `datasourceUid` | string | Yes | The UID of the Graphite datasource to query |

### List incidents

**Slug:** `GRAFANA_CLOUD_MCP_LIST_INCIDENTS`

List Grafana incidents. Allows filtering by status ('active', 'resolved') and optionally including drill incidents. Returns a preview list with basic details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `drill` | boolean | No | Whether to include drill incidents |
| `limit` | integer | No | The maximum number of incidents to return |
| `status` | string | No | The status of the incidents to include. Valid values: 'active', 'resolved' |

### List investigation evidence

**Slug:** `GRAFANA_CLOUD_MCP_LIST_INVESTIGATION_EVIDENCE`

List the evidence citation index for one Grafana Assistant investigation (AI-driven root-cause investigation) by ID.

Investigation reports cite captured query panels with [cite:pN] markers. Each evidence entry describes one captured panel, keyed by that panel ID: the tool that produced it (prometheus, loki, tempo, pyroscope), a human-readable query summary, the epoch (agent turn) at capture time, the capture timestamp, and the tool call ID that produced it.

This is an index, not the data: raw query results live in the investigation thread. To see the data behind a citation, call get_investigation_thread and match the entry's toolUseId against the thread's tool results. Legacy (v1) investigations have no engine session and return an empty list.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `investigationId` | string | Yes | Investigation ID, as returned by list_investigations or create_investigation. |

### List investigation profiles

**Slug:** `GRAFANA_CLOUD_MCP_LIST_INVESTIGATION_PROFILES`

List the agent profiles available for Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack.

Each profile describes an investigation agent configuration: its ID, display name, description, whether it is the default, its step budget, the tools it can use, and its content hash. Use a profile's ID as agentProfileId when creating an investigation.

### List investigations

**Slug:** `GRAFANA_CLOUD_MCP_LIST_INVESTIGATIONS`

List Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack.

Returns one summary per investigation — ID, chat ID, title, state, timestamps, labels, team ownership, progress, and completion quality — plus the total count of matches for pagination. Results are limited to investigations the authenticated user is allowed to see.

All filters are optional. Use chatId to find the investigation that owns a known chat (all other filters are then ignored), q for free-text search, state/scope/label/teamName/from/to to narrow results, and limit/offset with the returned total to paginate.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Search text matched against investigation title, description, or chat name. |
| `to` | string | No | Only investigations created at or before this RFC3339 timestamp. |
| `from` | string | No | Only investigations created at or after this RFC3339 timestamp. |
| `sort` | string | No | Sort field: createdAt, updatedAt, title, or state. |
| `view` | string | No | Response projection: full or lite. |
| `label` | string | No | Filter by label in key:value format. |
| `limit` | integer | No | Maximum number of investigations to return. |
| `order` | string | No | Sort order: asc or desc. |
| `scope` | string ("all" | "mine" | "teams" | "system") | No | Visibility scope: all, mine, teams, or system. |
| `state` | string | No | Filter by investigation state: pending, in_progress, completed, failed, cancelled, or paused. |
| `chatId` | string | No | Find the investigation owning this chat ID. Returns a singleton (or empty) list. When set, all other filters are ignored. |
| `offset` | integer | No | Number of investigations to skip, for pagination. |
| `teamName` | string | No | Filter investigations to a specific team by name. |
| `archivedOnly` | boolean | No | Return only investigations whose backing chat is archived. Overrides includeArchived when true. |
| `includeLegacy` | boolean | No | Also include legacy (v1) investigations in results. |
| `includeArchived` | boolean | No | Include investigations whose backing chat is archived. |

### List loki label names

**Slug:** `GRAFANA_CLOUD_MCP_LIST_LOKI_LABEL_NAMES`

Lists all available label/field names (keys) found in logs within a specified Loki or VictoriaLogs datasource and time range. Returns a list of unique label strings (e.g., `["app", "env", "pod"]`). If the time range is not provided, it defaults to the last hour.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `endRfc3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `startRfc3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### List loki label values

**Slug:** `GRAFANA_CLOUD_MCP_LIST_LOKI_LABEL_VALUES`

Retrieves all unique values associated with a specific `labelName` within a Loki or VictoriaLogs datasource and time range. Returns a list of string values (e.g., for `labelName="env"`, might return `["prod", "staging", "dev"]`). Useful for discovering filter options. Defaults to the last hour if the time range is omitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labelName` | string | Yes | The name of the label to retrieve values for (e.g. 'app', 'env', 'pod') |
| `endRfc3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `startRfc3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### List oncall schedules

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ONCALL_SCHEDULES`

List Grafana OnCall schedules, optionally filtering by team ID. If a specific schedule ID is provided, retrieves details for only that schedule. Returns a list of schedule summaries including ID, name, team ID, timezone, and shift IDs. Supports pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | The page number to return (1-based) |
| `teamId` | string | No | The ID of the team to list schedules for |
| `scheduleId` | string | No | The ID of the schedule to get details for. If provided, returns only that schedule's details |

### List oncall teams

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ONCALL_TEAMS`

List teams configured in Grafana OnCall. Returns a list of team objects with their details. Supports pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | The page number to return |

### List oncall users

**Slug:** `GRAFANA_CLOUD_MCP_LIST_ONCALL_USERS`

List users from Grafana OnCall. These are OnCall users (separate from Grafana users). Can retrieve all users in the OnCall directory, a specific user by ID, or filter by username. Returns a list of user objects with their details. Supports pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | The page number to return |
| `userId` | string | No | The ID of the user to get details for. If provided, returns only that user's details |
| `username` | string | No | The username to filter users by. If provided, returns only the user matching this username |

### List prometheus label names

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PROMETHEUS_LABEL_NAMES`

List label names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Optionally, the maximum number of results to return |
| `matches` | array | No | Optionally, a list of label matchers to filter the results by |
| `endRfc3339` | string | No | Optionally, the end time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now') |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `startRfc3339` | string | No | Optionally, the start time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now-1h') |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### List prometheus label values

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PROMETHEUS_LABEL_VALUES`

Use after list_prometheus_metric_names to find label values for filtering queries. Gets the values for a specific label name in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Optionally, the maximum number of results to return |
| `matches` | array | No | Optionally, a list of selectors to filter the results by |
| `labelName` | string | Yes | The name of the label to query |
| `endRfc3339` | string | No | Optionally, the end time of the query. Supports RFC3339 or relative time (e.g. 'now') |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `startRfc3339` | string | No | Optionally, the start time of the query. Supports RFC3339 or relative time (e.g. 'now-1h') |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### List prometheus metric metadata

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PROMETHEUS_METRIC_METADATA`

List Prometheus metric metadata. Returns metadata about metrics currently scraped from targets. Note: This endpoint is experimental.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | The maximum number of metrics to return |
| `metric` | string | No | The metric to query |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `datasourceUid` | string | Yes | The UID of the datasource to query |
| `limitPerMetric` | integer | No | The maximum number of metrics to return per metric |

### List prometheus metric names

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PROMETHEUS_METRIC_NAMES`

DISCOVERY: Call this first to find available metrics before querying. Lists metric names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Retrieves all metric names and filters them using the provided regex. Supports pagination and an optional time range to restrict results to metrics active within that window.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | The page number to return |
| `limit` | integer | No | The maximum number of results to return |
| `regex` | string | No | The regex to match against the metric names |
| `endRfc3339` | string | No | Optionally, the end time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now') |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `startRfc3339` | string | No | Optionally, the start time of the time range to filter the results by. Supports RFC3339 or relative time (e.g. 'now-1h') |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### List pyroscope label names

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PYROSCOPE_LABEL_NAMES`


Lists all available label names (keys) found in profiles within a specified Pyroscope datasource, time range, and
optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}). Returns a
list of unique label strings (e.g., ["app", "env", "pod"]). Label names with double underscores (e.g. __name__) are
internal and rarely useful to users. If the time range is not provided, it defaults to the last hour.


#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `matchers` | string | No |  |
| `end_rfc_3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `start_rfc_3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `data_source_uid` | string | Yes | The UID of the datasource to query |

### List pyroscope label values

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PYROSCOPE_LABEL_VALUES`


Lists all available label values for a particular label name found in profiles within a specified Pyroscope datasource,
time range, and optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}).
Returns a list of unique label strings (e.g. for label name "env": ["dev", "staging", "prod"]). If the time range
is not provided, it defaults to the last hour.


#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | A label name |
| `matchers` | string | No | Optionally, Prometheus style matchers used to filter the result set (defaults to: {}) |
| `end_rfc_3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `start_rfc_3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `data_source_uid` | string | Yes | The UID of the datasource to query |

### List pyroscope profile types

**Slug:** `GRAFANA_CLOUD_MCP_LIST_PYROSCOPE_PROFILE_TYPES`


Lists all available profile types available in a specified Pyroscope datasource and time range. Returns a list of all
available profile types (example profile type: "process_cpu:cpu:nanoseconds:cpu:nanoseconds"). A profile type has the
following structure: <name>:<sample type>:<sample unit>:<period type>:<period unit>. Not all profile types are available
for every service. If the time range is not provided, it defaults to the last hour.


#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end_rfc_3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `start_rfc_3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `data_source_uid` | string | Yes | The UID of the datasource to query |

### List snapshots

**Slug:** `GRAFANA_CLOUD_MCP_LIST_SNAPSHOTS`

List Grafana dashboard snapshots with optional query and result limit filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of snapshots to return (Grafana defaults to 1000 when omitted) |
| `query` | string | No | Optional search query for snapshot name |

### List snowflake tables

**Slug:** `GRAFANA_CLOUD_MCP_LIST_SNOWFLAKE_TABLES`

START HERE for Snowflake: List available tables (database, schema, name, kind, row count, size) via INFORMATION_SCHEMA. NEXT: Use describe_snowflake_table to see column schemas.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schema` | string | No | Schema name to filter tables (lists all non-system schemas if not specified). |
| `database` | string | No | Database name to scan (uses INFORMATION_SCHEMA in this database). Defaults to the datasource's configured database. |
| `datasourceUid` | string | Yes | The UID of the Snowflake datasource |

### List team roles

**Slug:** `GRAFANA_CLOUD_MCP_LIST_TEAM_ROLES`

List all roles assigned to one or more teams. Returns a map of team IDs to their assigned roles.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `teamIds` | array | Yes | Team ID(s) to get roles for. Can be a single team or multiple teams. |

### List teams

**Slug:** `GRAFANA_CLOUD_MCP_LIST_TEAMS`

Search for Grafana teams by a query string. Returns a list of matching teams with details like name, ID, and URL.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | The query to search for teams. Can be left empty to fetch all teams |

### List user roles

**Slug:** `GRAFANA_CLOUD_MCP_LIST_USER_ROLES`

List all roles assigned to one or more users. Returns a map of user IDs to their assigned roles, excluding built-in roles and team-inherited roles.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `userIds` | array | Yes | User ID(s) to get roles for. Can be a single user or multiple users. |

### List users by org

**Slug:** `GRAFANA_CLOUD_MCP_LIST_USERS_BY_ORG`

List users in the Grafana organization. Returns a list of organization users with details like userid, email, role etc.

### Query athena

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_ATHENA`

Query Amazon Athena via Grafana. REQUIRED FIRST: Use list_athena_catalogs -> list_athena_databases -> list_athena_tables -> describe_athena_table to discover schema, then query.

Supports macros: $__timeFilter(column), $__dateFilter(column), $__unixEpochFilter(column), $__timeFrom(), $__timeTo(), $__from, $__to, $__interval, ${varname}

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Athena queries are async — Grafana handles polling. Use LIMIT and partition-aware WHERE clauses to avoid timeouts on large tables.

Example: SELECT request_time, status FROM my_table WHERE $__timeFilter(request_time) LIMIT 100

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time. Formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: now. |
| `limit` | integer | No | Appended as LIMIT when query has none (default: 100). Existing LIMIT clauses are capped at 1000 regardless of this parameter. |
| `query` | string | Yes | Raw SQL query. Supports macros: $__timeFilter(column), $__dateFilter(column), $__unixEpochFilter(column), $__timeFrom(), $__timeTo(), $__from/$__to (Unix ms), $__interval, and ${varname} for variable substitution. |
| `start` | string | No | Start time. Formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: 1 hour ago. |
| `region` | string | No | AWS region override. Defaults to datasource config. |
| `catalog` | string | No | Data catalog override. Defaults to datasource config. |
| `database` | string | No | Database override. Defaults to datasource config. |
| `variables` | object | No | Template variable substitutions as key-value pairs. Referenced as ${varname} or $varname in the query. |
| `datasourceUid` | string | Yes | The UID of the Athena datasource. Use list_datasources to find available UIDs. |
| `resultReuseEnabled` | boolean | No | Enable Athena query result reuse to avoid redundant scans and reduce cost. Requires Athena engine version 3. |
| `resultReuseMaxAgeInMinutes` | integer | No | Maximum age in minutes for reused query results. Only applies when resultReuseEnabled is true. |

### Query clickhouse

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_CLICKHOUSE`

Query ClickHouse via Grafana. REQUIRED FIRST: Use list_clickhouse_tables to find tables, then describe_clickhouse_table to see column schemas, then query.

Supports macros: $__timeFilter(column), $__from, $__to, $__interval, ${varname}

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Example: SELECT Timestamp, Body FROM otel_logs WHERE $__timeFilter(Timestamp)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the query. Time formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to now. |
| `limit` | integer | No | Maximum number of rows to return. Default: 100, Max: 1000. If query doesn't contain LIMIT, one will be appended. |
| `query` | string | Yes | Raw SQL query. Supports ClickHouse macros: $__timeFilter(column) for time filtering, $__from/$__to for millisecond timestamps, $__interval/$__interval_ms for calculated intervals, and ${varname} for variable substitution. |
| `start` | string | No | Start time for the query. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to 1 hour ago. |
| `variables` | object | No | Template variable substitutions as key-value pairs. Variables can be referenced as ${varname} or $varname in the query. |
| `datasourceUid` | string | Yes | The UID of the ClickHouse datasource to query. Use list_datasources to find available UIDs. |

### Query cloudwatch

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_CLOUDWATCH`

Query AWS CloudWatch metrics via Grafana. Requires region.

REQUIRED FIRST: Use list_cloudwatch_namespaces -> list_cloudwatch_metrics -> list_cloudwatch_dimensions -> then query.

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Common namespaces: AWS/EC2, AWS/ECS, AWS/RDS, AWS/Lambda, ECS/ContainerInsights

Example dimensions: ECS: {ClusterName, ServiceName}, EC2: {InstanceId}

Cross-account monitoring: Use accountId to query metrics from a specific source account (e.g. '123456789012') or 'all' to query all linked accounts. Only applicable when using a CloudWatch monitoring account datasource.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time. Formats: 'now', '2026-02-02T20:00:00Z', '1738522800000' (Unix ms). Default: now |
| `start` | string | No | Start time. Formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Default: now-1h |
| `period` | integer | No | Period in seconds (default: 300) |
| `region` | string | Yes | AWS region (e.g. us-east-1) |
| `accountId` | string | No | AWS account ID for cross-account monitoring. Specify an account ID to query metrics from a specific source account, or 'all' to query all accounts the monitoring account is permitted to query. Only relevant when using a CloudWatch monitoring account datasource. |
| `namespace` | string | Yes | CloudWatch namespace (e.g. AWS/ECS, AWS/EC2, AWS/RDS, AWS/Lambda) |
| `statistic` | string ("Average" | "Sum" | "Maximum" | "Minimum" | "SampleCount") | No | Statistic type: Average, Sum, Maximum, Minimum, SampleCount. Default: Average |
| `dimensions` | object | No | Dimensions as key-value pairs (e.g. {"ClusterName": "my-cluster"}) |
| `metricName` | string | Yes | Metric name (e.g. CPUUtilization, MemoryUtilization, Invocations) |
| `datasourceUid` | string | Yes | The UID of the CloudWatch datasource to query. Use list_datasources to find available UIDs. |

### Query elasticsearch

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_ELASTICSEARCH`

Executes a search query against an Elasticsearch or OpenSearch datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'status:200 AND host:server1') for both Elasticsearch and OpenSearch. Elasticsearch Query DSL JSON is also supported for Elasticsearch datasources only (not OpenSearch). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs, metrics, or any indexed data stored in Elasticsearch or OpenSearch. Defaults to 10 results and sorts by @timestamp in descending order (newest first).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `index` | string | Yes | The index pattern to search (e.g., 'logs-*', 'filebeat-*', or a specific index name) |
| `limit` | integer | No | Optionally, the maximum number of documents to return (max: 100, default: 10) |
| `query` | string | Yes | The search query. For Elasticsearch datasources, this can be either Lucene query syntax (e.g., 'status:200 AND host:server1') or Elasticsearch Query DSL JSON (for advanced queries with aggregations). For OpenSearch datasources, only Lucene query syntax is supported. |
| `endTime` | string | No | Optionally, the end time. Filters results to documents with the configured time field (default @timestamp) <= this value. Supports RFC3339 (e.g. '2024-01-01T23:59:59Z'), relative to now (e.g. 'now', 'now-1h'), or Unix timestamps |
| `startTime` | string | No | Optionally, the start time. Filters results to documents with the configured time field (default @timestamp) >= this value. Supports RFC3339 (e.g. '2024-01-01T00:00:00Z'), relative to now (e.g. 'now', 'now-1h', 'now-30m'), or Unix timestamps |
| `datasourceUid` | string | Yes | The UID of the Elasticsearch or OpenSearch datasource to query |

### Query graphite

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_GRAPHITE`

WORKFLOW: list_graphite_metrics -> query_graphite.

Executes a Graphite render API query against a Graphite datasource and returns matching metric series with their datapoints. Supports the full Graphite target expression language including wildcard patterns (e.g. 'servers.web*.cpu.load5'), aggregation functions (e.g. 'sumSeries(app.*.requests)'), and tag-based queries (e.g. 'seriesByTag(\'name=cpu.load\')'). Datapoints with no recorded value are returned with a null value field. Time range defaults to the last hour if not specified.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `from` | string | No | Start of the time range. Accepts RFC3339 (e.g. '2024-01-01T00:00:00Z') or Graphite relative times (e.g. '-1h', '-24h'). Defaults to '-1h'. |
| `until` | string | No | End of the time range. Accepts RFC3339 or Graphite relative times (e.g. 'now'). Defaults to 'now'. |
| `target` | string | Yes | The Graphite target expression to evaluate (e.g. 'servers.web*.cpu.load5', 'sumSeries(app.*.requests)', 'seriesByTag(\'name=cpu.load\')') |
| `datasourceUid` | string | Yes | The UID of the Graphite datasource to query |
| `maxDataPoints` | integer | No | Optional maximum number of data points per series. Graphite consolidates data when the requested range exceeds this value. |

### Query graphite density

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_GRAPHITE_DENSITY`

Analyses metric data density for one or more Graphite series over a time window. Returns per-series statistics: fillRatio (fraction of non-null datapoints, 0.0–1.0), totalPoints, nonNullPoints, lastSeen (Unix timestamp of most recent non-null value, or null if none), longestGap (longest consecutive null run in seconds), and estimatedInterval (inferred write interval in seconds). Supports wildcard targets (e.g. 'obox-cl*.sys.sessions') to diagnose stale, sparse, or dead metrics across a cluster. A fillRatio of 0 with lastSeen null means the series reported no data in the requested window.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `from` | string | No | Start of the time range. Accepts RFC3339 or Graphite relative times (e.g. '-1h'). Defaults to '-1h'. |
| `until` | string | No | End of the time range. Accepts RFC3339 or Graphite relative times (e.g. 'now'). Defaults to 'now'. |
| `target` | string | Yes | Graphite target expression; supports wildcards (e.g. 'obox-cl*.sys.sessions') |
| `datasourceUid` | string | Yes | The UID of the Graphite datasource to query |

### Query influxdb

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_INFLUXDB`

Query an InfluxDB datasource via Grafana. Supports both InfluxQL (v1.x) and Flux (v2.x). The 'dialect' parameter selects the query language; if omitted it's inferred from the datasource configuration.

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

InfluxQL example: SELECT mean("value") FROM "cpu" WHERE time > now() - 1h GROUP BY time(1m)
Flux example:    from(bucket: "metrics") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu")

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the query. Time formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to now. |
| `query` | string | Yes | Raw query string. InfluxQL for v1.x datasources (e.g. SELECT * FROM cpu WHERE time > now() - 1h), or Flux for v2.x datasources (e.g. from(bucket: "mybucket") &#124;> range(start: -1h)). |
| `start` | string | No | Start time for the query. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to 1 hour ago. |
| `dialect` | string | No | Query dialect: 'influxql' or 'flux'. If omitted, inferred from the datasource's configured query language (v1 -> influxql, v2 -> flux). |
| `datasourceUid` | string | Yes | The UID of the InfluxDB datasource to query. Use list_datasources to find available UIDs. |
| `maxDataPoints` | integer | No | Maximum number of data points to return. Default: 1000. |

### Query loki logs

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_LOKI_LOGS`

Executes a log query against a Loki or VictoriaLogs datasource and returns matching log entries (or metric samples on Loki). Defaults to the last hour, a limit of 10 entries, and 'backward' direction (newest first). The `logql` parameter takes LogQL on Loki and LogsQL on VictoriaLogs (e.g., Loki: `{app="foo"} |= "error"`; VictoriaLogs: `{app="foo"} "error"`). To count matching log lines precisely, use a `count_over_time()` metric query with queryType='instant'. Prefer using `query_loki_stats` first to cheaply check whether a stream contains data (avoiding expensive queries against empty streams) and `list_loki_label_names` / `list_loki_label_values` to verify labels exist before querying. Note: `query_loki_stats` returns approximate storage-level counts, not exact log line counts. For broad queries that match many lines, set `format` to 'compact' to group results by stream and avoid repeating label metadata on every line. If this server enables the Loki cost guardrail, expensive queries are rejected before execution: query cost is bytes SCANNED, determined only by the stream selector and time range — line filters (|=) and parsers (| json) reduce what is returned, not what is scanned. Use a stream selector with at least one selective positive label matcher (never `{}`, `=~".*"`/`=~".+"`, or negative-only matchers), keep time ranges narrow, and check size with `query_loki_stats` first; rejected queries return rewrite guidance.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Optionally, the maximum number of log lines to return (default max: 100, configurable by MCP server). |
| `logql` | string | Yes | The LogQL query to execute against Loki. This can be a simple label matcher or a complex query with filters, parsers, and expressions. Supports full LogQL syntax including label matchers, filter operators, pattern expressions, and pipeline operations. |
| `format` | string ("full" | "compact") | No | Output format for log (streams) queries: 'full' (default) returns every entry with its own label metadata; 'compact' groups lines by stream so each label set is emitted only once (and per-line structured/parsed metadata is dropped), substantially reducing response size for broad queries. Ignored for metric queries. |
| `direction` | string | No | Optionally, the direction of the query: 'forward' (oldest first) or 'backward' (newest first, default) |
| `queryType` | string | No | Query type: 'range' (default) or 'instant'. Instant queries return a single value at one point in time. Range queries return values over a time window. Use 'instant' for metric queries when you want the current value. |
| `endRfc3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') |
| `stepSeconds` | integer | No | Resolution step in seconds for range metric queries. When running metric queries with queryType='range', this controls the time resolution of the returned data points. |
| `startRfc3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### Query loki patterns

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_LOKI_PATTERNS`

Retrieves detected log patterns from a Loki datasource for a given stream selector and time range. Returns a list of patterns, each containing a pattern string and a total count of occurrences. Patterns help identify common log structures and anomalies. The `logql` parameter must be a stream selector (e.g., `{job="nginx"}`) and does not support line filters or aggregations. Defaults to the last hour if the time range is omitted. **Not supported on VictoriaLogs** datasources - use a `| stats` pipeline instead.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `step` | string | No | Optionally, the query resolution step (e.g. '5m') |
| `logql` | string | Yes | A LogQL stream selector to identify the logs to analyze for patterns (e.g. {job="foo", namespace="bar"}) |
| `endRfc3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') (defaults to now) |
| `startRfc3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### Query loki stats

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_LOKI_STATS`

Retrieves index-level statistics about log streams matching a given selector within a Loki or VictoriaLogs datasource and time range. Returns an object containing the count of streams, chunks, entries, and total bytes (e.g., `{"streams": 5, "chunks": 50, "entries": 10000, "bytes": 512000}`). **Important**: the `entries` count reflects storage-level index entries (chunk metadata), NOT the number of individual log lines matching the selector. To count actual matching log lines, use `query_loki_logs` with a `count_over_time()` metric query instead. On VictoriaLogs only `entries` is populated; the other fields remain zero. The `logql` parameter **must** be a simple label selector (e.g., `{app="nginx", env="prod"}`) and does not support line filters, parsers, or aggregations. Defaults to the last hour if the time range is omitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logql` | string | Yes | The LogQL matcher expression to execute. This parameter only accepts label matcher expressions and does not support full LogQL queries. Line filters, pattern operations, and metric aggregations are not supported by the stats API endpoint. Only simple label selectors can be used here. |
| `endRfc3339` | string | No | Optionally, the end time of the query in RFC3339 format or relative time (e.g. 'now') |
| `startRfc3339` | string | No | Optionally, the start time of the query in RFC3339 format or relative time (e.g. 'now-1h') |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### Query prometheus

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_PROMETHEUS`

WORKFLOW: list_prometheus_metric_names -> list_prometheus_label_values -> query_prometheus. Query a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.) using a PromQL expression. Supports instant queries (single point) and range queries (time range). Time: RFC3339 or relative expressions like 'now'\, 'now-1h'.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `expr` | string | Yes | The PromQL expression to query |
| `endTime` | string | Yes | The end time. Supported formats are RFC3339 or relative to now (e.g. 'now', 'now-1.5h', 'now-2h45m'). Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h', 'd'. |
| `queryType` | string | No | The type of query to use. Either 'range' or 'instant' |
| `startTime` | string | No | The start time. Required if queryType is 'range', ignored if queryType is 'instant' Supported formats are RFC3339 or relative to now (e.g. 'now', 'now-1.5h', 'now-2h45m'). Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h', 'd'. |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `stepSeconds` | integer | No | The time series step size in seconds. Required if queryType is 'range', ignored if queryType is 'instant' |
| `datasourceUid` | string | Yes | The UID of the datasource to query |

### Query prometheus histogram

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_PROMETHEUS_HISTOGRAM`

Query Prometheus histogram percentiles. DISCOVER FIRST: Use list_prometheus_metric_names with regex='.*_bucket$' to find histograms.

Generates histogram_quantile PromQL. Example: metric='http_duration', percentile=95, labels='job="api"'

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `labels` | string | No | Label selector (e.g. job="api", service="gateway") |
| `metric` | string | Yes | Base histogram metric name (without _bucket suffix) |
| `endTime` | string | No | End time (default: now). Supports RFC3339, relative, or Unix ms. |
| `startTime` | string | No | Start time (default: now-1h). Supports RFC3339, relative (now-1h), or Unix ms. |
| `percentile` | number | Yes | Percentile to calculate (e.g. 50, 90, 95, 99) |
| `projectName` | string | No | GCP project name to query (Cloud Monitoring datasources only). Overrides or substitutes the defaultProject configured on the datasource. |
| `stepSeconds` | integer | No | Step size in seconds for range query (default: 60) |
| `rateInterval` | string | No | Rate interval for the query (default: 5m) |
| `datasourceUid` | string | Yes | The UID of the Prometheus datasource |

### Query pyroscope

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_PYROSCOPE`


Unified Pyroscope query tool for fetching profiles or metrics from Pyroscope. Profile data shows WHICH functions consume resources; metrics data
shows WHEN consumption spiked. Use query_type="both" for complete analysis in one call.

query_type options (extends Grafana's PyroscopeQueryType):
- "profile": returns profile data (shape controlled by format)
- "metrics": returns time-series data points
- "both" (default): returns both profile and metrics in one response

format options (shape of the profile data):
- "table" (default): per-function table with flat (self) and cumulative values, ranked by flat
- "dot": call graph in Graphviz DOT format; nodes are per source line, so one function may span several nodes


#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `step` | number | No | Seconds between metrics data points (default: auto) |
| `format` | string | No | Profile output format: "table" (default) for a per-function flat/cum table, or "dot" for a call graph in Graphviz DOT format |
| `group_by` | array | No | Labels to group metrics series by |
| `matchers` | string | No | Prometheus style matchers (defaults to: {}) |
| `query_type` | string | No | Query type: "profile" (flamegraph), "metrics" (time-series), or "both" (default). Use "both" for complete analysis |
| `end_rfc_3339` | string | No | End time in RFC3339 or relative time (e.g. 'now') (defaults to now) |
| `profile_type` | string | Yes | The profile type, use list_pyroscope_profile_types to discover available types |
| `max_node_depth` | integer | No | Max functions in the profile table or nodes in the call graph; it is a count, not a depth (default: 100) |
| `start_rfc_3339` | string | No | Start time in RFC3339 or relative time (e.g. 'now-1h') (defaults to 1 hour ago) |
| `data_source_uid` | string | Yes | The UID of the datasource to query |

### Query quickwit

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_QUICKWIT`

Executes a search query against a Quickwit datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'severity_text:ERROR AND service_name:api') and partial Elasticsearch-compatible Query DSL JSON. The timestamp field is resolved from Quickwit index metadata (not jsonData.timeField). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs or other indexed data stored in Quickwit. Defaults to 10 results and sorts by the index timestamp field in descending order (newest first).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `index` | string | No | Optionally, the index or index pattern to search. Defaults to the index configured on the datasource (jsonData.index) |
| `limit` | integer | No | Optionally, the maximum number of documents to return (max: 100, default: 10) |
| `query` | string | Yes | The search query in Lucene syntax (e.g., 'severity_text:ERROR AND service_name:api') or partial Elasticsearch-compatible Query DSL JSON |
| `endTime` | string | No | Optionally, the end time. Filters results to documents with timestamp <= this value. Supports RFC3339 (e.g. '2024-01-01T23:59:59Z'), relative to now (e.g. 'now', 'now-1h'), or Unix timestamps |
| `startTime` | string | No | Optionally, the start time. Filters results to documents with timestamp >= this value. Supports RFC3339 (e.g. '2024-01-01T00:00:00Z'), relative to now (e.g. 'now', 'now-1h', 'now-30m'), or Unix timestamps |
| `datasourceUid` | string | Yes | The UID of the Quickwit datasource to query |

### Query snowflake

**Slug:** `GRAFANA_CLOUD_MCP_QUERY_SNOWFLAKE`

Query Snowflake via Grafana. REQUIRED FIRST: Use list_snowflake_tables to find tables (filter by database/schema), then describe_snowflake_table to see column schemas, then query.

Supports macros: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to, $__interval, $__interval_ms, ${varname}

Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Snowflake event tables (telemetry from logging APIs/auto-instrumentation) live in the database/schema configured by the EVENT TABLE setting; the standard one is SNOWFLAKE.TELEMETRY.EVENTS.

Example: SELECT TIMESTAMP, RECORD['severity_text']::STRING AS LEVEL, VALUE FROM SNOWFLAKE.TELEMETRY.EVENTS WHERE $__timeFilter(TIMESTAMP) AND RECORD_TYPE = 'LOG'

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the query. Time formats: 'now', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to now. |
| `limit` | integer | No | Maximum number of rows to return. Default: 100, Max: 1000. If query doesn't contain LIMIT, one will be appended. |
| `query` | string | Yes | Raw SQL query. Supports Snowflake macros: $__timeFilter(column) for time filtering, $__timeFrom/$__timeTo for TIMESTAMP_NTZ literals, $__from/$__to for millisecond timestamps, $__interval/$__interval_ms for calculated intervals, and ${varname} for variable substitution. Use 3-part names (DATABASE.SCHEMA.TABLE) for cross-database queries; SNOWFLAKE.TELEMETRY.EVENTS is the standard event table. |
| `start` | string | No | Start time for the query. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms). Defaults to 1 hour ago. |
| `variables` | object | No | Template variable substitutions as key-value pairs. Variables can be referenced as ${varname} or $varname in the query. |
| `datasourceUid` | string | Yes | The UID of the Snowflake datasource to query. Use list_datasources to find available UIDs. |

### Run panel query

**Slug:** `GRAFANA_CLOUD_MCP_RUN_PANEL_QUERY`

Executes one or more dashboard panel queries with optional time range and variable overrides. Accepts an array of panel IDs to query in a single call. Fetches the dashboard\, extracts queries from the specified panels\, substitutes template variables and Grafana macros ($__range\, $__rate_interval\, $__interval)\, and routes to the appropriate datasource (Prometheus\, Loki\, ClickHouse\, CloudWatch\, InfluxDB\, BigQuery\, MSSQL\, or PostgreSQL). Returns results keyed by panel ID - partial failures are allowed (some panels can succeed while others fail). Use get_dashboard_summary first to find panel IDs. If a panel uses a template variable datasource you cannot access\, provide datasourceUid and datasourceType to override.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | Override end time (e.g. 'now', RFC3339, Unix ms) |
| `start` | string | No | Override start time (e.g. 'now-1h', RFC3339, Unix ms) |
| `panelIds` | array | Yes | Panel IDs to execute (one or more) |
| `variables` | object | No | Override dashboard variables (e.g. {"job": "api-server"}) |
| `queryIndex` | integer | No | Index of the query to execute per panel (0-based, defaults to 0). Use get_dashboard_panel_queries to see all queries. |
| `dashboardUid` | string | Yes | Dashboard UID |
| `datasourceUid` | string | No | Override datasource UID |
| `datasourceType` | string | No | Override datasource type (prometheus, loki, grafana-clickhouse-datasource, cloudwatch, influxdb, grafana-bigquery-datasource, mssql, grafana-postgresql-datasource, postgres) |

### Search dashboards

**Slug:** `GRAFANA_CLOUD_MCP_SEARCH_DASHBOARDS`

Search for Grafana dashboards by a query string. Returns a list of matching dashboards with details like title, UID, folder, tags, and URL.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-indexed) |
| `limit` | integer | No | Maximum number of results to return (max 100) |
| `query` | string | No | The query to search for |

### Search folders

**Slug:** `GRAFANA_CLOUD_MCP_SEARCH_FOLDERS`

Search for Grafana folders by a query string. Returns matching folders with details like title, UID, and URL.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | The query to search for |

### Search plugin information

**Slug:** `GRAFANA_CLOUD_MCP_SEARCH_PLUGIN_INFORMATION`

Search the Grafana plugin catalog by keyword to discover available plugins before installing or getting plugin details on a specific instance. Returns results sorted by trust: official Grafana Labs plugins first, then commercial partner plugins, then community plugins. Use this tool when a user describes a plugin by purpose or partial name (e.g. 'azure monitoring', 'loki', 'database') — it returns the exact pluginId to pass to get_plugin or install_plugin. Results include warnings for enterprise-only or Angular-based plugins.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Keyword to search for plugins (e.g. 'azure', 'prometheus', 'loki', 'database'). Matches against plugin name, slug, description, and keywords. |

### Suggest loki alloy label config

**Slug:** `GRAFANA_CLOUD_MCP_SUGGEST_LOKI_ALLOY_LABEL_CONFIG`

Generates an Alloy loki.process snippet enforcing an approved label set via stage.label_keep, with optional log-level normalisation and soft-enforcement placeholders.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `forwardTo` | string | No |  |
| `componentName` | string | No |  |
| `approvedLabels` | array | Yes | Labels to keep on the index. |
| `requiredLabels` | array | No | Labels that get an 'unknown' placeholder when missing. |
| `normalizeLogLevel` | boolean | No |  |

### Tempo docs-config

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_DOCS_CONFIG`

Documentation on Tempo configuration. Best for questions about how to configure or operate Tempo. Request the overview to learn which configuration block does what, or the reference for the complete list of options and their defaults.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string ("config-overview" | "config-reference") | Yes | The type of Tempo configuration documentation to retrieve |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo docs-traceql

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_DOCS_TRACEQL`

Documentation on TraceQL search. Best for retrieval of traces. This covers basic attributes all the way through aggregates, pipelining, structural queries, and more. Includes examples.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string ("basic" | "aggregates" | "structural" | "metrics") | Yes | The type of TraceQL documentation to retrieve |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo get-attribute-names

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_GET_ATTRIBUTE_NAMES`

Get a list of available attribute names that can be used in TraceQL queries. This is useful for finding the names of attributes that can be used in a query.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | string | No | Optional scope to filter attributes by (span, resource, event, link, instrumentation). If not provided, returns all attributes. |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo get-attribute-values

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_GET_ATTRIBUTE_VALUES`

Get a list of values for a fully scoped attribute name. This is useful for finding the values of a specific attribute. i.e. you can find all the services in the data by asking for resource.service.name

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The attribute name to get values for (e.g. 'span.http.method', 'resource.service.name') |
| `filter-query` | string | No | Filter query to apply to the attribute values. It can only have one spanset and only &&'ed conditions like { <cond> && <cond> && ... }.This is useful for filtering the values to a specific set of values. i.e. you can find all endpoints for a given service by asking for span.http.endpoint and filtering resource.service.name. |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo get-trace

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_GET_TRACE`

Retrieve a specific trace by ID

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `trace_id` | string | Yes | Trace ID to retrieve |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo traceql-metrics-instant

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_TRACEQL_METRICS_INSTANT`

Retrieve a single metric value given a TraceQL metrics query. The value is at the current instant or end. Most metrics questions can be answered with instant values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be after start. |
| `query` | string | Yes | TraceQL query string. |
| `start` | string | No | Start time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be before end. |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo traceql-metrics-range

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_TRACEQL_METRICS_RANGE`

Retrieve a metric series given a TraceQL metrics query. The series ranges from start to end.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be after start. |
| `query` | string | Yes | TraceQL metrics query string. |
| `start` | string | No | Start time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be before end. |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Tempo traceql-search

**Slug:** `GRAFANA_CLOUD_MCP_TEMPO_TRACEQL_SEARCH`

Search for traces using TraceQL queries

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be after start. |
| `query` | string | Yes | TraceQL query string |
| `start` | string | No | Start time for the search (RFC3339 format). If not provided will search the past 1 hour. If provided, must be before end. |
| `datasourceUid` | string | Yes | UID of the tempo datasource to query |

### Update alert group

**Slug:** `GRAFANA_CLOUD_MCP_UPDATE_ALERT_GROUP`

Update the state of a Grafana OnCall alert group: acknowledge, unacknowledge, resolve, or unresolve it by ID. Returns the alert group's resulting OnCall state (one of new, acknowledged, resolved, silenced), or a stateWarning explaining why that state could not be read back after a successful update.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | string | Yes | New state for the alert group. One of: acknowledged, unacknowledged, resolved, unresolved |
| `alertGroupId` | string | Yes | The ID of the alert group to update |

### Update annotation

**Slug:** `GRAFANA_CLOUD_MCP_UPDATE_ANNOTATION`

Updates the provided properties of an annotation by ID. Only fields included in the request are modified; omitted fields are left unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | No | Annotation ID to update |
| `data` | object | No | Optional JSON payload |
| `tags` | array | No | Tags to replace existing tags |
| `text` | string | No | New annotation text |
| `time` | integer | No | New start time epoch ms |
| `timeEnd` | integer | No | New end time epoch ms |

### Update dashboard

**Slug:** `GRAFANA_CLOUD_MCP_UPDATE_DASHBOARD`

Create or update a dashboard. Two modes: (1) Full JSON — provide 'dashboard' for new dashboards or complete replacements. (2) Patch — provide 'uid' + 'operations' to make targeted changes to an existing dashboard. One of these two modes is required; 'folderUid'\, 'message'\, and 'overwrite' are supplementary and do nothing on their own. Dashboard authoring guidance: if a saved query must support one\, many\, or All values from a multi-select variable inside a regex expression or matcher\, save '${var:regex}' rather than plain '$var'. Saved dashboard annotation queries/definitions must be written into dashboard JSON under 'annotations.list'; the create_annotation tool creates annotation events and does not add a reusable dashboard annotation query/definition to the saved dashboard. For stat panels over the current dashboard range\, make the query return the range-level result the stat should display; panel-side reduction only reduces returned series and does not compute peak-over-range or ratio-of-peaks semantics for you. Patch operations support JSONPaths like '$.panels[0].targets[0].expr'\, '$.panels[1].title'\, '$.panels[2].targets[0].datasource'\, '$.templating.list/-'\, and '$.annotations.list/-'. Append to arrays with '/- ' syntax: '$.panels/- '. Remove by index: {"op": "remove"\, "path": "$.panels[2]"}. Multiple removes on the same array are automatically reordered to avoid index-shifting issues. Note: only numeric array indices are supported in patch paths; filter expressions like [?(@.id==2)] and wildcards like [*] are not supported. v2 dashboards (check 'isV2' from get_dashboard_by_uid) use a different shape: patch '$.elements.<name>.spec.title' or '$.elements.<name>.spec.data.spec.queries[0].spec' and edit '$.variables'/'$.layout' rather than '$.panels'/'$.templating.list'. Full-JSON saves containing top-level 'elements'/'layout' are written as v2 and require a Kubernetes-capable Grafana. After creating or updating a dashboard\, verify that panel queries return data by using `run_panel_query` or the appropriate query tool (`query_prometheus`\, `query_loki_logs`\, etc.) to validate expressions before considering the task complete.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | No | UID of existing dashboard to update. Must be used together with 'operations'. Providing 'uid' without 'operations' will fail. |
| `userId` | integer | No | ID of the user making the change |
| `message` | string | No | Set a commit message for the version history |
| `dashboard` | object | No | The full dashboard JSON. Use for creating new dashboards or complete updates. Saved dashboard annotation queries/definitions live in 'annotations.list' inside this JSON; they are different from annotation events created with create_annotation. Large dashboards consume significant context - consider using patches for small changes. |
| `folderUid` | string | No | The UID of the dashboard's folder |
| `overwrite` | boolean | No | Overwrite the dashboard if it exists. Otherwise create one |
| `operations` | array | No | Array of patch operations for targeted updates. More efficient than full dashboard JSON for small changes. Common paths: '$.templating.list/-' to add a variable, '$.annotations.list/-' to add a saved dashboard annotation query/definition, '$.panels[0].targets[0].expr' to replace a panel query. |

### Update datasource

**Slug:** `GRAFANA_CLOUD_MCP_UPDATE_DATASOURCE`

Update non-secret datasource fields by UID. Omitted fields are preserved. IMPORTANT: always call this tool twice. First call: provide only the uid — the tool returns the datasource's field schema. After receiving the schema, ask the user which fields they want to change and confirm each new value; do not infer or reset fields the user did not mention. Second call: provide the uid, schemaReviewed=true, and the changed values in the fields map. Returns an update message and a health check. For secrets, direct the user to the Grafana UI.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uid` | string | Yes | UID of the datasource to update |
| `url` | string | No | Base URL |
| `name` | string | No | Display name |
| `access` | string | No | proxy or direct |
| `fields` | object | No | Datasource field values to change, keyed by field key from the schema returned on the first call. The server uses each field's target (root or jsonData) to place values correctly, merging jsonData changes into the existing settings. Only include the fields you want to change. Example: {"httpMethod": "POST"}. |
| `database` | string | No | Database name |
| `jsonData` | object | No | Non-secret plugin settings; replaces existing jsonData when set |
| `basicAuth` | boolean | No | Enable basic auth |
| `isDefault` | boolean | No | Make this the default datasource |
| `schemaReviewed` | boolean | No | Set to true on the second call to confirm you reviewed the schema and collected the changes from the user. |

### Update incident

**Slug:** `GRAFANA_CLOUD_MCP_UPDATE_INCIDENT`

Update an existing Grafana incident by ID. Allows changing the status ('active' or 'resolved'), the severity, and the title. Only the provided fields are changed. Use this to resolve an incident or to correct its severity or title as part of an on-call workflow.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | No | The new title of the incident |
| `status` | string | No | The new status of the incident. Valid values: 'active', 'resolved' |
| `severity` | string | No | The new severity of the incident, e.g. 'minor', 'major', 'critical' |
| `incidentId` | string | Yes | The ID of the incident to update |