Provides tools for interacting with Grafana instances, enabling agents to search dashboards and folders, read dashboard JSON models, list datasources, query datasources, inspect alert rules and annotations, and (with elevated modes) create/update dashboards and folders, write annotations, and delete with safeguards.
Enables querying Prometheus datasources through Grafana's unified query API using PromQL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-grafana search dashboards for 'checkout' and query prometheus for error rates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A safe-by-default Model Context Protocol server for Grafana. It lets an agent explore and operate Grafana — search dashboards, read the dashboard JSON model, list and query datasources (Prometheus / Loki / SQL), inspect alert rules and annotations, and (in higher modes) create/update dashboards and folders, write annotations, and delete.
Part of the dockndevai MCP server suite — one governance model across all of them.
The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.
Tool | For | Needs mode |
| check the instance is up, version | read-only |
| find dashboards & folders by name/tag (get UIDs) | read-only |
| enumerate dashboards / folders | read-only |
| the full dashboard JSON model + meta | read-only |
| datasources (secrets redacted) | read-only |
| run PromQL / LogQL / SQL via the unified query API | read-only |
| Grafana-managed alert rules | read-only |
| events overlaid on graphs | read-only |
| upsert a dashboard (versioned, reversible) | read-write |
| create a folder | read-write |
| mark a deploy/incident on graphs | read-write |
| delete (irreversible) | admin + |
Related MCP server: Grafana MCP Server
npx -y @dockndevai/mcp-grafanaYou need a Grafana service account token (Administration → Service accounts → Add service account → Add token). Give it the least role that works — Viewer for read-only use, Editor to create/update, Admin only if you must delete.
{
"mcpServers": {
"grafana": {
"command": "npx",
"args": ["-y", "@dockndevai/mcp-grafana"],
"env": {
"GRAFANA_URL": "http://localhost:3000",
"GRAFANA_TOKEN": "glsa_...",
"GRAFANA_MODE": "read-only"
}
}
}
}See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.
The access model is enforced by src/security.ts — defence in depth on top of the service-account token's own role:
GRAFANA_MODE — read-only (default) → read-write → admin. A tool is registered only if the mode allows its capability. Read-only exposes the 11 read tools; edits need read-write; deletes need admin.
GRAFANA_ALLOW_DELETE — deletes are irreversible, so on top of admin mode they also require this flag.
GRAFANA_FOLDER_ALLOWLIST / GRAFANA_PROTECTED_FOLDERS — confine which folders can be written to; mark folders (e.g. production) that may be read but never modified or deleted.
GRAFANA_DATASOURCE_ALLOWLIST — restrict which datasources query_datasource may hit.
GRAFANA_DRY_RUN — validate and log writes without executing them.
GRAFANA_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).
Interactive confirmation — when the client supports MCP elicitation, deleting a dashboard/folder/annotation prompts the human to approve before it runs; clients that can't elicit fall back to the GRAFANA_ALLOW_DELETE gate.
Secrets are never returned — datasource secureJsonData, passwords and tokens are stripped from every response.
See SECURITY.md.
Conventions for the dashboard JSON model, panel/target shapes, PromQL/LogQL/SQL query patterns, folder organisation and safe editing live in the bundled skill: .claude/skills/grafana-dashboards-and-queries/SKILL.md. Agents that load it can build and edit dashboards to a consistent standard without being re-taught each time.
npm install
npm run build
GRAFANA_URL=http://localhost:3000 GRAFANA_TOKEN=glsa_… node dist/index.js
# introspect without a live Grafana:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | GRAFANA_TOKEN=x node dist/index.jsMIT
Return the full dashboard JSON model (panels, targets, templating, time) plus meta (folder, version, url) for a dashboard UID. This is the model you edit and pass back to create_or_update_dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Dashboard UID (from search). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the description's main added value is disclosing the return structure (panels, targets, templating, time, folder, version, url) and its role as the editable model. It does not mention authentication requirements, error behavior for invalid UIDs, or rate limits, but for a read-only retrieval tool the added context is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the core return content front-loaded. Every clause earns its place by specifying either the output shape or the downstream use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple by-UID retrieval tool with no output schema, the description adequately explains what is returned (full model plus meta) and how it fits into an edit workflow. Annotations already cover the safety profile, so nothing critical is missing for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single uid parameter already documented as coming from search. The description only repeats that the tool works 'for a dashboard UID' and adds no syntax, format, or lookup guidance beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Return) and resource (full dashboard JSON model), and explicitly distinguishes itself from list-style siblings by specifying the full model including panels, targets, templating, and time. An agent can immediately tell this is a by-UID retrieval tool, not a listing or search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use it: to obtain the editable model for a dashboard UID, especially for passing to create_or_update_dashboard. However, it does not explicitly name alternative tools like list_dashboards or search, nor does it state when not to use it (e.g., when only a summary is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a single datasource by UID (secrets redacted).
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds a genuinely useful behavioral detail not present in structured data: returned secrets are redacted, telling the agent credentials will be absent from the payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with the verb, scope, key, and an important caveat front-loaded; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full annotation coverage and no output schema, the description is nearly sufficient: it explains selection and the redaction behavior. It could still note the not-found/error case, which is the main remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the schema only declares uid as a non-empty string, so the description must carry the meaning. Saying 'by UID' does identify the parameter as the datasource selector, but adds no format, source, or uniqueness details beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (Return), resource (a single datasource), and retrieval key (by UID). The singular 'single datasource' implicitly separates it from the plural list_datasources and the action-oriented query_datasource, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: fetch one datasource when its UID is known. There is no explicit statement of when to prefer this over list_datasources or query_datasource, and no mention of error behavior for an unknown UID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a folder's details by UID.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that—no error behavior for an unknown UID, no auth or permission context, no note on what 'details' includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with the action and resource, no filler. It is efficient if slightly under-specified rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with annotations covering the behavioral profile and no output schema, the core intent is conveyed. Missing pieces are what a 'folder detail' contains and what happens on a miss, both minor for this tool class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single uid parameter, but the description compensates minimally by naming the lookup key ('by UID'). It still doesn't state the UID format or where a UID comes from, so it does not fully close the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Return) and resource (a folder's details) with the lookup key (UID). It doesn't differentiate itself from siblings like get_dashboard or list_folders, but the get_* family convention makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus list_folders or get_dashboard, and no prerequisites noted. The agent must infer that this is the single-item fetch by UID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the Grafana instance is reachable and return its version and database status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the useful behavior that it reports version and database status — meaningful because there is no output schema to reveal the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The action and the returned information both land immediately, and nothing is repeated from the title or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only probe with annotations covering safety and no output schema, the description supplies the essential facts: what is verified and what comes back. Only a hint about the response format or failure behavior is absent, which is a small omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so there is nothing to disambiguate; the 4 baseline applies. The schema is empty and coverage is 100%, leaving no semantic gaps for the description to fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('check ... is reachable') plus the exact resource (Grafana instance) and the payload it returns (version, database status). It is unambiguously distinct from every sibling, which all operate on dashboards, folders, datasources, alerts, or annotations rather than instance health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Check the Grafana instance is reachable' clearly implies the usage context (connectivity/health verification before or after other calls). No alternatives or exclusions are named, but for a parameterless singleton health probe there is no sibling to route against, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Grafana-managed alert rules (via the provisioning API): title, condition, folder, state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real context beyond them: the rules are Grafana-managed (as opposed to data-source-managed) and come via the provisioning API, and it names the returned fields. It stops short of noting pagination or whether all folders are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the verb and resource, with the scoping qualifier and returned-field list appended. No filler sentences and nothing repeated from the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the return fields (title, condition, folder, state) and pins the rule scope to Grafana-managed rules. The only gaps are pagination/result-size behavior and whether filtering by folder is possible, which are minor for a zero-param tool whose safety profile is already in annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so per the baseline this dimension starts at 4. The description correctly adds nothing about inputs and instead documents the output fields, which is the only semantic content available.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (Grafana-managed alert rules), plus the access path (provisioning API) and the exact fields returned (title, condition, folder, state). No sibling in the set covers alert rules, so there is no ambiguity to resolve; an agent knows immediately what this returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and by the explicit scope 'Grafana-managed', but there is no statement of when to prefer this over other listing tools or any precondition/limitation. For a zero-parameter lister with no close sibling this is adequate but not instructive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List annotations (events overlaid on graphs), optionally within a time range or by tag.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Range end, epoch ms. | |
| from | No | Range start, epoch ms. | |
| tags | No | Restrict to annotations with these tags. | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, fully covering the safety and repeatability profile. The description adds the domain gloss but says nothing about default limits, pagination, or ordering. Against rich annotations, this is adequate but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and resource, with the filters trailing as optional. No wasted words, though the parenthetical is the only added value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description could have described the return shape (annotation fields, ordering, pagination) and it does not. For a simple read-only list tool with strong annotations and 75% schema coverage this is serviceable, but the agent is left to infer the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so from/to and tags are already documented in the schema; the description restates the same filters ('time range', 'by tag') without adding format or semantics. The limit parameter is undocumented in both schema and description. Baseline 3 fits given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (annotations), and adds a clarifying gloss '(events overlaid on graphs)' that tells the agent what an annotation actually is. The resource is distinct from every sibling (dashboards, folders, datasources, alert rules), so no explicit sibling routing is needed, but there is no active differentiation text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'optionally within a time range or by tag' implies the usage mode (unfiltered list vs filtered list) but never states when to reach for this tool, when not to, or what alternative exists. Usage is inferred rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dashboards (optionally filtered by tag). Shorthand for search with type=dash-db.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Restrict to a tag. | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: no pagination behavior, no default limit, no note on how many results come back. It is essentially a name expansion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core action stated first and the sibling-relationship note second. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter list tool with annotations covering safety and no output schema, the description is close to adequate but leaves the `limit` parameter and any pagination/result-count behavior unexplained. Minor but real gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: `tag` is described in the schema and echoed in the description, while `limit` has only min/max bounds and no prose anywhere. The description confirms the tag filter's purpose but does not compensate for the undocumented limit semantics (default value, cap of 1000).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list dashboards) and adds a scoping note (optional tag filter) plus an equivalence to the sibling `search` with type=dash-db. That differentiates it from get_dashboard and search, though it does not explicitly name get_dashboard as the single-item alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'shorthand for search with type=dash-db' clause implies when this is preferable to the generic search tool, but it never states exclusions, prerequisites, or when to reach for search/list_folders instead. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured datasources (uid, name, type, url). Secrets (secureJsonData, passwords, tokens) are never returned. Use the uid with query_datasource.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that by stating secrets (secureJsonData, passwords, tokens) are never returned, which tells the agent what to expect in the payload. It does not address pagination or result limits, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: what is listed and its fields, the secrecy guarantee, and the chaining hint. Front-loaded with the core purpose and zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description partially compensates by naming the returned fields and the excluded secret fields, which is the most important return-value information. It omits ordering/pagination behavior, a minor gap for a simple zero-arg list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parenthetical field list describes outputs rather than inputs and is not misleading.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (configured datasources), and enumerates the returned fields (uid, name, type, url), which cleanly separates it from get_datasource and query_datasource. An agent can pick it without opening a sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use the uid with query_datasource" gives an explicit follow-on workflow, making the intended role in a list-then-query chain clear. It stops short of stating when NOT to use it (e.g., a single known datasource should use get_datasource), so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dashboard folders with their UIDs and titles.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is fully covered. The description only adds that results carry UIDs and titles, which is useful but thin; it says nothing about ordering, pagination, or whether empty results are possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste. The resource is named first and the return contents are appended without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and a full annotation set, the remaining burden is describing what comes back, and the description does name the two returned fields. It stops short of covering ordering or pagination, but for a trivial zero-arg listing tool this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. The mention of UIDs and titles describes output rather than input, which is harmless but not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List dashboard folders") and adds the returned fields ("their UIDs and titles"), so the agent knows exactly what this produces. It does not explicitly distinguish itself from siblings like get_folder or list_dashboards, but the plural/list framing makes the scope self-evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this versus get_folder (single folder) or list_dashboards, and no prerequisites or ordering guidance. Usage is only implied by the verb 'List', which is weak guidance for a tool sitting among several list/get siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a query against a datasource through Grafana's unified query API and return the result frames. For Prometheus/Loki set expr (PromQL / LogQL); for SQL datasources set rawSql. Reading data only — this never mutates anything. Use a bounded time range and a small maxDataPoints to keep results manageable.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Range end, e.g. 'now'. Default now. | |
| expr | No | PromQL or LogQL expression, e.g. 'up' or 'rate(http_requests_total[5m])'. | |
| from | No | Range start, e.g. 'now-1h' or an epoch ms string. Default now-1h. | |
| rawSql | No | SQL for SQL datasources (a single read-only SELECT). | |
| datasourceUid | Yes | Datasource UID (from list_datasources). | |
| maxDataPoints | No | Cap on returned points. Default 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Reading data only — this never mutates anything' largely restates structured data. It does add one useful behavioral fact (results come back as result frames) and performance guidance about bounding time range/maxDataPoints, but says nothing about auth needs, rate limits, or error behavior for a mutating-adjacent remote call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then dialect-specific parameter selection, then a practical constraint. No filler; every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query tool with full schema coverage and read-only/idempotent annotations, the description covers purpose, parameter selection, and safety sufficiently; with no output schema, the brief mention of 'result frames' is adequate but thin. Minor omission: no guidance on result size, pagination, or failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds the conditional mapping between expr (PromQL/LogQL) and rawSql (SQL) that the schema documents only in isolation. It does not clarify from/to formatting or maxDataPoints tradeoffs beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run a query against a datasource through Grafana's unified query API and return the result frames'), and the sibling set (list_*/get_* tools) is clearly non-overlapping, so the agent can route here without ambiguity. It also names the two query dialects it supports, which sharpens what 'query' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent which parameter to use per datasource family ('for Prometheus/Loki set expr ... for SQL datasources set rawSql') and advises a bounded time range with small maxDataPoints. It lacks any when-not-to-use or alternative-tool routing, but no sibling overlaps this capability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search dashboards and folders by name/tag. Use this first to find a dashboard's UID before get_dashboard. Returns title, uid, type (dash-db | dash-folder), folder and tags.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Restrict to a dashboard tag. | |
| type | No | Restrict to dashboards or folders. | |
| limit | No | ||
| query | No | Free-text match on title. Omit to list everything. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value by enumerating the returned fields (title, uid, type, folder, tags) in the absence of an output schema, though it says nothing about limit/pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and scope, then usage ordering, then return shape. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description's enumeration of return fields is genuinely needed and present. It omits guidance on the undocumented 'limit' parameter and default result behavior, a minor gap for a zero-required-parameter search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema largely documents itself. The description restates the tag/name matching dimension and repeats the type enum values already present in the schema, adding little beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search dashboards and folders by name/tag') and clarifies scope by naming the searchable fields. It distinguishes itself from get_dashboard, though it does not differentiate from the sibling list_dashboards/list_folders, which overlap in intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to 'use this first to find a dashboard's UID before get_dashboard,' giving a concrete sequencing rule. It lacks a when-not clause or a comparison against list_dashboards, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0get_dashboardget_datasourceget_folderget_healthlist_alert_ruleslist_annotationslist_dashboardslist_datasourceslist_foldersquery_datasourcesearchScored across 11 tools
Most tools have distinct resource+action purposes (get_health, get_dashboard, get_folder, get_datasource, query_datasource, list_alert_rules, list_annotations). The only real overlap is list_dashboards vs search, but the description explicitly frames list_dashboards as shorthand for search with type=dash-db, which mitigates the ambiguity.
Names follow a clear verb_noun convention (list_*, get_*, query_*), making the pattern predictable. 'search' is the lone deviation without an explicit noun, and 'get_health' is slightly idiosyncratic, but overall consistency is strong.
11 tools is well within the ideal 3-15 range for a Grafana integration. Each tool maps to a concrete resource or operation, and none feel redundant or filler.
Read coverage is broad (dashboards, folders, datasources, alert rules, annotations, health), but the surface is almost entirely read-only. Notably, get_dashboard references passing the model back to 'create_or_update_dashboard,' a tool that does not exist, and there is no create/update/delete for dashboards, folders, annotations, or alert rules — a meaningful lifecycle gap.
Provide real-time data querying and visualization by integrating Tako with your agents. Generate o…
One place to build, share, and govern the skills and tools your AI agents use at work.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
Give your AI agents the tools to build, manage, and run automation workflows.
