Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, but the description adds genuinely new behavioral facts: it reports whether write tools are registered, and it explains the silent-org-selection hazard of service account tokens. It also covers the unconfigured-server case ('says exactly what to set'), removing the main failure-mode ambiguity.

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 purpose and followed by the call-conditions. The opening sentence is a long packed enumeration, which costs some readability, but no clause is 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?

No output schema exists, yet the description enumerates the return surface in enough detail that an agent knows what it will get back. Combined with the misconfiguration and trust caveats, nothing material is missing for a zero-arg diagnostic 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?

Zero parameters, so there is nothing to disambiguate; baseline for an empty schema is 4. The description correctly implies the tool takes no input.

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 plus resource ('Report which Grafana and which organization this server reads, as whom') and enumerates the exact fields returned: URL, version, org id/name, login identity, effective role/permissions, write-tool registration. The diagnostic framing cleanly separates it from every sibling (query/search/list tools).

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?

Gives two concrete triggers: 'Call this first when a tool you expected is missing' and 'before trusting data from an instance you have not checked.' It also supplies the reason ('a service account token picks its org silently'), which is exactly the kind of condition-based routing an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the read-only and open-world profile, and the description adds genuinely useful cost/omission detail: summary drops layout, styling and overrides ("typically half the JSON"), full "can be tens of KB" and carries `version`. It stops short of error behavior (unknown uid, missing/invalid panel_id) but discloses the main behavioral trade-offs of each mode.

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?

Front-loaded with the core action, then ordered by mode, with the sibling redirect last where an agent will look for it. Dense but no filler; the one compressed clause ("the layout, styling and overrides left out, typically half the JSON") takes a re-read but earns its space.

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 carries the return-shape burden — and it does: it enumerates what summary contains (variables, panels with id/type/unit/queries), what panel returns (full panel JSON), and what full returns (whole JSON plus `version`). Combined with the save/query cross-references, an agent has enough to pick a mode and call it 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining what each enum value of `view` actually yields and the conditional dependency that panel_id is required only for view=panel — semantics the terse schema enum text does not convey. `uid` and `panel_id` sourcing are left to the schema, which already handles them well.

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 + resource ("Read a dashboard") immediately followed by the three operating modes, each with a concrete definition of what is returned. It differentiates from siblings by naming grafana_save_dashboard (round-trip consumer of view=full) and grafana_run_panel_query (data instead of query 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?

Explicitly routes each need to a mode: summary is the default for 'what is on it', panel needs panel_id, full is what save_dashboard needs back. It also names the correct alternative for a different intent ("To see the DATA a panel shows, use grafana_run_panel_query instead of reading its query and re-typing it"), including the anti-pattern to avoid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly and openWorld; the description adds real behavioral detail beyond them: result ordering ('Firing first, then pending'), per-rule fields returned including lastError on evaluation failure, and the cost caveat that include_query 'is most of the size'. It does not mention pagination/truncation, but the limit parameter covers that.

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?

Four tight sentences, no filler, with the source scope and ordering constraint front-loaded and the redirect to the sibling tool placed last where it belongs. The opening sentence is slightly dense but every clause carries 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 an 8-param, no-output-schema listing tool, the description carries the return-value burden well by enumerating what each rule contains. Only minor gaps: nothing about result ordering guarantees under filtering or what a truncated (limit-capped) result looks like.

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 100%, so baseline would be 3, but the description adds meaning the schema lacks: it ties include_query to payload-size cost and clarifies the alert/record interaction of the type parameter. group/folder and unhealthy semantics remain schema-only.

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+resource ('The alert rules and their evaluation state') and explicitly scopes the source set to Grafana-managed alerting plus every self-evaluating Prometheus/Loki datasource. It is clearly distinguishable from grafana_list_alerts, which is named as covering alert instances rather than rules.

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 routes the agent: 'Use grafana_list_alerts for the alert instances themselves' and states that recording rules are excluded 'unless type=record or all'. That gives both a when-not and an override condition, though other overlapping siblings (search, silences) are not addressed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint=true / openWorldHint=true, the description discloses real behavior: mandatory severity ordering, suppression excluded by default, `common_labels` deduplicated once, and — notably — that severity/alertname counts cover the entire match set even when the returned list is truncated by limit. That last detail is a non-obvious result-shape trait no structured field conveys.

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 dense sentences, front-loaded with the core question ('What is alerting right now') and ending with the aggregation caveat. No filler, though the final sentence packs two distinct behaviors (common_labels and counts-under-truncation) into one clause.

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, open-world read tool with no output schema, the description covers what comes back, ordering, default filtering, deduplication, and count semantics under pagination. It leaves the multi-source aggregation model (how grafana vs datasource alerts combine) and any auth expectations unstated, but nothing blocking for a correct call.

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 all six parameters are already documented with examples and enum semantics. The description only reinforces the state parameter's suppression behavior and the truncation effect of limit; it adds little syntax or meaning the schema doesn't already carry.

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?

It states exactly what the tool returns — the alerts currently firing in Grafana's Alertmanager plus every Alertmanager datasource, ordered most-severe-first, with since/summary/description fields. That phrasing cleanly separates it from siblings like grafana_list_alert_rules (rule definitions) and grafana_list_silences (suppressions) without needing to name them.

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 rather than stated: the description tells you what 'right now' means and how suppressed alerts are gated behind state=suppressed or all, but never says when to reach for this vs grafana_list_alert_rules or grafana_list_silences. An agent must infer the routing from the sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description goes further by disclosing result ordering (newest first), the fields each annotation carries, and the type=alert distinction. Missing only operational detail such as truncation/limit behavior at the 1000 cap.

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 tight sentences with the core scope front-loaded, then return shape, then a usage heuristic. The middle sentence's field list is slightly dense but each item earns its place by compensating for the absent output schema.

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 7-parameter, all-optional read tool with no output schema, the description covers scope, ordering, and returned fields so an agent knows what comes back. It could say more about empty results or how filters combine, but nothing essential is missing.

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% and already documents relative-time syntax, tag AND-semantics, the type enum and limits. The description only echoes the window concept and type=alert, adding little syntax or format meaning beyond the schema — baseline 3 applies.

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 ('Annotations in a time window, newest first') and enumerates what they are: deploys, incidents, notes, and alert state changes flagged via type=alert. That last clause usefully separates it from the grafana_list_alerts / grafana_list_alert_rules siblings, though those tools are not named outright.

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?

Gives a concrete scenario ('what changed around the spike?') and the recommended invocation pattern — a window around the spike with no other filter. Clear positive guidance, but no explicit when-not / named-alternative routing (e.g. 'for current firing alerts use grafana_list_alerts instead').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value beyond them by disclosing a data boundary: 'Credentials and plugin settings are never returned', which tells the agent what is safe to surface. It does not discuss completeness of the listing or permission/auth requirements, keeping it short of 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, zero padding, and the returned-fields list is front-loaded immediately after the verb. Every sentence carries information an agent needs: scope, invocation context, and return boundary.

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 compensates by naming the returned fields (uid, name, type, default flag) and excluding sensitive ones. Combined with fully covered parameter docs, an agent has everything needed to select and call it 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%, so both the `type` and `search` filters are already documented with examples in the schema, making 3 the baseline. The description mentions plugin types (prometheus, loki, alertmanager, postgres) but that echoes the schema's own example rather than adding new filtering 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 (list) plus the resource (datasources) and enumerates the returned fields: uid, name, type, default flag. It also positions the tool relative to siblings by noting that every query tool consumes a datasource by uid or name, so an agent knows this is the discovery step preceding grafana_query/grafana_query_prometheus.

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 sentence 'Every query tool takes a datasource by uid or name' gives clear implied usage: call this first to resolve a datasource reference. It stops short of explicit when-not guidance or naming a specific alternative (e.g. when to use grafana_search instead), so it is clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only and open-world, so the bar is lower; the description adds real value by disclosing the default one-hour window versus the datasource's whole-retention default, which is a genuine surprise-avoidance detail. It also documents the `__name__` special case for Prometheus. It does not mention result limits or cost of broad selectors, which would have earned 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?

Front-loaded with the core behavior, then mode-switching, then scoping, then the default-window caveat. Dense but every clause carries information; the em-dash construction is slightly heavy but not wasteful.

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?

Seven optional parameters, all schema-documented, and the description covers mode selection, scoping, and time defaults — enough for correct invocation. Since there is no output schema, a brief note on the returned shape (flat list vs. paginated) would have closed the 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 coverage is 100%, so baseline is 3; the description goes further by explaining the semantic switch on `label` (absent = names, present = values, `__name__` = metric names) and giving a concrete `selector` example. It leaves `limit`, `search`, and `end` entirely to the schema, which is acceptable given full coverage.

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 (discover/list label names and values) scoped to Prometheus or Loki datasources, and immediately distinguishes the two modes via `label`. An agent can tell this apart from grafana_query / grafana_query_prometheus, which fetch data rather than metadata, without opening any 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?

Gives clear conditional usage: omit `label` to enumerate label names, supply it to enumerate values, and use `selector` to narrow to relevant series/streams. The time-window guidance ('looks at the last hour unless start is given') is a concrete usage rule. It stops short of naming an explicit alternative tool or stating when-not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly and openWorld, so the description's addition that expired silences are filtered out by default (and how to include them) is genuine behavioral context an agent would otherwise miss. Pagination/limit behavior is left entirely to the schema.

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 compact sentences with the resource and scope first, then the field list and the expired-silence caveat. The fragmentary opening ('The silences in…') is slightly awkward but wastes no words.

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?

A simple read-only list tool with no output schema, and the description covers sources, returned fields, and the default exclusion behavior — enough for correct invocation. Only the absence of routing guidance against sibling listing tools leaves a 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 coverage is 100%, so limit, search, source and the state enum are already fully documented, including the same 'current/expired/all' semantics. The description adds no format examples or edge-case detail beyond the schema baseline.

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?

Names the concrete resource (silences) and the scope (Grafana's Alertmanager plus every Alertmanager datasource), and enumerates the returned fields, so the agent knows this is a read of silence state rather than alerts or rules. It does not explicitly contrast with siblings like grafana_list_alerts, so it stops short of a 5.

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 return-field list, and the note that expired silences are excluded unless state=expired or all hints at the main selection decision. There is no explicit 'use this when… instead of…' guidance relative to the other list_* tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the core safety profile is covered. The description adds useful behavioral context: it names the raw endpoint, explains that queries are panel-JSON target objects, gives an expression example, and warns that dashboard variables are not substituted. It does not cover auth requirements or error behavior, but that is less critical given the annotations.

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?

The description is dense and front-loaded: it leads with the core action, then query-object semantics, then alternatives, then the variable caveat. Every sentence carries useful routing or behavioral 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?

Given full parameter schema coverage, clear annotations, and no output schema, the description supplies what an agent needs: the endpoint behavior, query-object form, sibling alternatives, and the important variable-substitution limitation. No essential invocation context is missing.

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. The description still adds conceptual meaning for the `queries` parameter by explaining that each query is the target object from a panel's JSON and by demonstrating server-side expressions with `__expr__`, which goes beyond the schema's example.

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 action (run raw queries), resource (any datasource), and endpoint (/api/ds/query), and clearly distinguishes this generic tool from dedicated siblings like grafana_query_prometheus and grafana_query_loki. It also calls out server-side expressions as a distinct use case.

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 explicitly says when to use this tool (datasources with no dedicated tool, and __expr__ expressions) and when to prefer alternatives (grafana_query_prometheus, grafana_query_loki, grafana_run_panel_query). The caveat that dashboard variables are not filled in is a useful usage boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnlyHint/openWorldHint annotations to describe return shapes: log queries return lines newest first with time, level and per-line labels, with shared labels hoisted into common_labels and truncation at max_line_chars; metric queries return series on a step grid with stats. It also discloses a genuine cost/performance trap (full-selector scans, so keep ranges short) and a token-efficiency heuristic for counting.

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?

Four tight sentences: what it does, then return shape for each query mode, then the two rules that prevent bad calls. Concrete example LogQL is embedded inline rather than in a separate block, and the safety-critical advice (label matcher, short range) is placed where it will be read.

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?

There are 13 parameters and no output schema, so the description carries the burden of explaining what comes back; it does exactly that for both response modes, including the common_labels hoisting and truncation. Together with the fully documented schema and the read-only annotation, an agent has everything needed to call this correctly and interpret the result.

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 100%, so the schema already does the heavy lifting and the baseline is 3. The description still adds meaning by explaining how parameters shape the response: that max_line_chars cuts each line, that metric output arrives on a step grid, and that results are counted rather than listed. It doesn't re-explain the timestamp formats or enum semantics, but it doesn't need to.

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 opening sentence states a specific verb and resource ("Run LogQL through a Loki datasource"), and the following sentences split the tool into its two modes, log query vs metric query, with concrete example syntax for each. Because Loki/LogQL is named explicitly, an agent can distinguish this from grafana_query_prometheus and from the generic grafana_query without opening either 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?

It gives real operating guidance: always include a label matcher, keep the range short because Loki scans every line, and prefer a metric query over fetching lines when counting; the schema descriptions also point to grafana_list_labels and grafana_list_datasources for discovery. What's missing is explicit sibling routing (for example, when to prefer grafana_query or grafana_run_panel_query), so it stops just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly/openWorld, and the description goes well beyond them: it discloses the return shape (min/max/avg/last per series, one value per step on a shared grid, null where no sample), the `common_labels` de-duplication, and relative payload cost ('about a tenth of the size'). That cost/shape guidance is exactly what an agent needs to avoid token blowups.

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?

Four sentences, front-loaded with the default mode and the 'almost every question' heuristic, then progressive detail on range/stats and aggregation. No filler and no restatement of the tool name or title.

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 12-parameter tool with no output schema and thin annotations, the description covers mode choice, output shape, payload size, and aggregation strategy — enough to call it correctly. It says nothing about failure modes (bad PromQL, missing datasource) or what an empty result looks like, which is the 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 coverage is 100%, so baseline is 3; the description adds genuine meaning on top by explaining the mode tradeoff, the view+sort interaction for outlier hunting, and the step/scrape-interval floor. It reinforces rather than repeats parameter docs, though per-parameter edge cases (limit vs topk interplay, precision) are left mostly to the schema.

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 + resource: 'Evaluate PromQL through a Prometheus datasource', which cleanly separates it from the LogQL sibling grafana_query_loki and from panel/search tools. It also states the two operating modes up front, so an agent knows the shape of the call before opening the 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?

Gives explicit decision rules: instant is 'the right mode for almost every question', range is for shape-over-time, and 'use view=stats with sort=max to find outliers among many series'. It also states an anti-pattern ('Aggregate in the expression ... rather than fetching raw series'). It stops short of naming tool-level alternatives (grafana_query_loki, grafana_run_panel_query), which keeps it from a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, it discloses that only GET is ever sent, the answer is raw unshaped JSON, and output is truncated at max_chars. These are important behavioral details for an open-world escape-hatch tool.

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?

The description is front-loaded with 'Escape hatch' and packs endpoint examples, safety, output shape, and alternative guidance into two dense sentences 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?

For an open-world raw HTTP passthrough with no output schema, it covers the essential missing pieces: read-only behavior, unshaped JSON output, truncation, and when to prefer named tools. An agent has enough to call it 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%, so the schema already documents path, params, and max_chars well. The description reinforces usage with endpoint examples but does not add material parameter semantics beyond what the schema provides, making the baseline 3 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 explicitly calls itself an escape hatch for GET requests to Grafana HTTP API endpoints not covered by other tools, and it lists concrete endpoint families. This clearly distinguishes it from the named siblings like grafana_query and grafana_get_dashboard.

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 states exactly when to use it — for endpoints the other tools do not wrap — and explicitly says to prefer the named tools, which shape their output. This gives an agent a clear routing rule and alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover readOnly/openWorld, yet the description discloses the real behavioral contract: variable resolution precedence (vars > dashboard-saved > first value/All), that hidden queries and expressions are honored, that the variable values used and each query as sent are returned for verification, and the per-shape output format (grid+stats / lines / table). No output schema exists, so this disclosure is doing essential work.

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?

Front-loaded with the action and return contract, and every sentence carries information. It is dense but slightly overpacked in one paragraph, and the closing note on the default time range partially repeats the schema's from/to documentation.

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 an 11-param tool with a nested `vars` object and no output schema, the description covers return format, variable resolution and defaults well. It stops short of error behavior (unknown panel id, non-query panels) and any permission caveats, which would be the remaining useful additions.

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 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: the three-tier fallback for unfilled template variables and the default time range behavior. These explain how `vars` and the `from`/`to` omission actually behave, not just their formats.

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 dashboard panel's queries ... and return the data", with the panel-scoped framing that separates it from raw query siblings like grafana_query_prometheus or grafana_query. The added clause about template variables and hidden queries makes the operation's boundaries unmistakable.

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 description makes the usage context clear (reproduce what the dashboard would show, re-run with other values) and notes the default time range, but never names an alternative or states when to prefer grafana_query_prometheus/grafana_query instead of a panel query. Usage is implied by the panel framing rather than spelled out as routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, and the description adds useful behavior beyond that: it states the return fields (uid, title, folder, tags, URL), the default no-argument listing behavior, and the natural follow-up action. It omits ordering and pagination nuance beyond the limit parameter, keeping it just short of fully transparent.

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 tight sentences with no filler, front-loading the search criteria first, then the returned fields and follow-up action. The no-arguments behavior is placed last, which is appropriate.

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 read-only search tool with full schema coverage and no output schema, the description provides enough: it explains what is searched, what is returned, and how to use the result. Minor omissions such as ordering or pagination semantics are not critical for correct invocation.

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 100%, so the input schema already documents each parameter's meaning, enum, default, and constraints. The description echoes the main filtering dimensions and mentions the no-argument default, but adds little parameter detail beyond what the schema already provides, which is the expected baseline.

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 uses a specific verb ('Find') and names the exact resources ('dashboards and folders') plus the searchable facets. It also disambiguates from siblings by directing the agent to grafana_get_dashboard when a uid is needed.

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 clearly states when to use the tool (to locate dashboards/folders and then fetch one by uid) and what happens with no arguments. It does not explicitly contrast with sibling list tools such as grafana_list_datasources or grafana_list_alert_rules, so the alternative routing is only partially covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.