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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it explains this is a diagnostic walk of the full notification chain and warns that any single link can silently drop a notification without recording an error, which sets expectations about why the answer may be inconclusive.

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 a one-line purpose, then the investigative scope, then routing guidance. Every sentence carries distinct information — none of it restates the name or the 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?

No output schema exists, so the description has to carry some of that burden, and it does by listing the chain elements it inspects, which implies the structure of the answer. It stops short of describing the response shape or what an inconclusive result looks like, leaving a minor 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?

Only one parameter, 'event', with 100% schema description coverage including an example value. The description adds no syntax, format, or identifier-source detail beyond the schema, so the baseline of 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?

States a specific verb and resource — explaining whether an event produced a notification and what blocked it — and then enumerates the exact chain it walks (suppression, delivery attempts, trigger actions, media types, per-recipient filters). It explicitly differentiates itself from siblings by naming zabbix_problem for the underlying issue and zabbix_resolve for identifier extraction.

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 an explicit trigger condition: 'Use when the user asks why an alert did or did not arrive, or why a notification was missing.' It also states when NOT to use it, routing to zabbix_problem for the problem itself and zabbix_resolve to convert a pasted notification into identifiers.

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/idempotentHint/destructiveHint, so the safety profile is covered; the description still adds real value by disclosing the risk-registry refusal for unknown methods, the approval flow for writes, and the MCP read-only surface. Minor ambiguity remains between 'write methods produce a plan' and 'a write through this tool is refused', and it never says what the raw response looks like or whether it is paginated.

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 and logically ordered: what it does, how reads vs writes behave, then routing. Slight redundancy — the write refusal is stated twice ('go through approval', 'Over MCP this tool is read-only', 'A write through this tool is refused') — but each restatement disambiguates a genuinely confusing surface.

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 should ideally describe the return shape (raw Zabbix JSON), which it omits. It is otherwise complete for the routing decision an agent must make, covering read immediacy, write refusal, unknown-method refusal, and sibling alternatives.

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 only 2 params, so the schema already documents 'method' and 'params as JSON'. The description contributes only an inline example (host.get) and no format, pagination, or limits guidance 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 ('Call a Zabbix API method directly') and positions itself precisely as the raw escape hatch against a list of high-level siblings. An agent can distinguish it from zabbix_problems, zabbix_metrics_latest, etc. 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?

Explicit routing: 'Use when no high-level tool covers the question and a read method such as host.get is required', with a named fallback for problems/hosts/metrics/alert delivery and a redirect to zabbix_write or zabbix_plan_create for writes. When-to-use, when-not-to-use, and alternatives are all stated.

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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: the exact scope of collected data and the explicit contract that it 'reports facts and draws no conclusions; interpreting them is the caller's job,' which sets output expectations. It does not, however, mention result size, timeouts, or permission requirements.

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, front-loaded with the core purpose, then scope, then routing. The 'draws no conclusions' clause is not filler — it changes how the caller should treat the response.

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 carries the burden of describing return content, and it does so by enumerating the five data categories the snapshot includes. Combined with the explicit routing guidance and annotations covering the safety profile, an agent has everything needed to select and invoke this tool 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% and there is only one parameter, so the schema fully documents 'host' (name, fragment or identifier). The description never elaborates on the parameter or on how a fragment matches multiple hosts, so it adds nothing beyond the schema — baseline 3.

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 ('Collect') and resource ('diagnostic snapshot of one host'), then enumerates exactly what is gathered: host state, active problems, recent events, silent/unsupported items, maintenance windows. This is clearly distinguishable from siblings like zabbix_host_status and zabbix_unreachable, which it names.

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 an explicit trigger ('what is wrong with a named host' or 'one diagnostic pass instead of several queries') and names two alternatives with the conditions that select them: zabbix_host_status for a short status line, zabbix_unreachable for hosts Zabbix cannot poll. Nothing is left to inference.

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 safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real behavioral context the annotations cannot: matching is a case-insensitive substring over both technical and visible name, exact matches rank first, and name-guessing is the common cause of empty results. It does not cover truncation/pagination behavior itself, leaving that 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?

Three short paragraphs, zero filler, with the core purpose front-loaded, matching semantics second, and routing last. Each sentence 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?

There is no output schema, but the description covers purpose, usage boundaries, alternatives, and match semantics, and the truncation-reporting behavior is carried by the limit parameter's schema text. For a 4-param read tool this is nearly complete; only an explicit note on return shape or default result ordering when no search is given 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: how the search string is interpreted (case-insensitive substring across both name fields) and result ordering. It adds no detail on group, limit, or monitored beyond the schema, so it is a modest improvement over baseline rather than a full one.

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 first sentence gives a specific verb (Find) and resource (hosts) plus the matching modes (name fragment, pattern, group). It is immediately distinguishable from siblings like zabbix_host_status and zabbix_host_investigate, which the description explicitly routes to.

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 the tool ('the user is looking for a host and does not have its exact name, or wants the hosts in a group') and names two alternatives with their selecting conditions: zabbix_host_status for a short health check of one host, zabbix_host_investigate for a full diagnostic snapshot.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful non-structured context: it is an aggregate over several API calls and deliberately returns a handful of fields rather than thousands of characters of configuration, which tells the agent to expect a compact, possibly lossy response.

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 purpose and scope, then the aggregation behavior, then the routing guidance. Every sentence earns its place with 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?

For a single-parameter read tool with no output schema, the description covers what is returned (the four summary areas), how it is produced (aggregated over several calls), and when to choose a sibling instead. Nothing an agent needs in order to call it correctly 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 there is only one parameter ('host', documented as name/fragment/identifier). The description reinforces the single-named-host scope but adds no format or syntax detail beyond the schema, so the 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 ('Summarise one host') and enumerates the exact scope of the summary: availability, active problems, data freshness, maintenance. It explicitly distinguishes itself from zabbix_host_investigate and zabbix_hosts, so an agent can pick it without opening sibling schemas.

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 selection condition ('when the user wants a short health check of one named host') and names both alternatives with the condition that selects each: zabbix_host_investigate for the full diagnostic bundle, zabbix_hosts for name-fragment search. No inference required.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not: expired windows are returned by default and the rationale for that default, which explains why the result set may be larger than expected.

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?

Purpose is front-loaded in the first sentence, with the default-behavior justification and routing guidance following in a logical order. The explanation of why expired windows are visible is slightly more verbose than needed, but it earns its place by pre-empting a likely agent surprise.

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?

Covered: purpose, filter semantics, default behavior, and sibling routing, which is sufficient for a read-only list tool with no output schema. It does not describe the truncated-result indicator mentioned in the `limit` schema, a minor omission rather than a blocker.

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 all four parameters are already documented in the schema, which sets the baseline at 3. The description's note that expired windows are shown by default complements the `active` parameter's semantics but adds no syntax or format detail beyond 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?

The first sentence states a specific verb and resource ('List maintenance windows') plus a scope qualifier ('including expired ones'). It is immediately distinguishable from mutating siblings like zabbix_write and zabbix_resolve.

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 explicit trigger conditions ('which maintenance windows exist, which hosts are silenced, or whether a window has expired') and explicitly routes mutations to zabbix_write or zabbix_plan_create. Both the when-to-use and when-not-to-use cases are covered with named alternatives.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value the annotations don't: the window-syntax convention operators use and the aggregation semantics (min/max/average) of the returned data. It omits mention of truncation, though the schema's limit description 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?

Three short sentences, front-loaded with purpose, then syntax convention, then usage routing. No filler and nothing that fails to earn 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?

There is no output schema, so the description carries the burden of describing returns, and it does: min, max and average over the window. Combined with annotations covering safety and the schema covering all params, nothing an agent needs to call this correctly 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, and every parameter including defaults, bounds and examples is already documented. The description goes slightly beyond by framing the 'last' window in operator-friendly terms (30m, 2h, 24h, 7d), reinforcing how to write the value rather than just the regex.

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 ('Read an item's values over a time window') plus the aggregation produced (min, max, average). It explicitly differentiates from the two nearest siblings, so an agent can distinguish it 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 an explicit when-to-use condition ('user asks how a metric behaved over a period, or wants min/avg/max') and names both alternatives with their selecting conditions: zabbix_metrics_latest for the newest value only, zabbix_unreachable for host reachability. Routing is unambiguous.

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, idempotent, non-destructive profile, so the bar is lower, yet the description still adds high-value behavior: values are read from history because item.lastvalue returns a constant zero, the history type is derived automatically, and a wrong query silently returns nothing rather than an error. That silent-failure warning is exactly the kind of trait an agent cannot get from 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?

Front-loaded with the action, then the critical history caveat, then routing. Three short paragraphs with no filler, though the middle paragraph is dense enough that it could be trimmed slightly for a tool with only three parameters.

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 metrics lookup with complete schema coverage and full safety annotations, the description covers purpose, caveats and routing alternatives. With no output schema, return details are rightly left to the schema's truncation note, so nothing an agent needs 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 host, limit and search are already fully documented including the 1-500 range, default of 25, and truncation reporting. The description adds only the general notion of a host-and-item lookup, which does not extend the schema, so baseline 3 is right.

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 ('Show the newest value of a host's items') and immediately scopes it to one host and one item set, which separates it from the history and investigate siblings. An agent can route correctly 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?

Names the exact use case ('current value of an item, such as CPU, disk or a custom metric, on one host') and then gives two explicit alternatives with their selecting conditions: zabbix_metrics_history for a time window, zabbix_host_investigate for a host that stopped sending data. Nothing is left to inference.

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 destructiveHint=false, and the description is consistent with them by stating 'Nothing changes until it is applied.' It adds value beyond the annotations by disclosing the return shape ('a plan identifier and the exact command the operator must run to apply it') and the apply workflow. It stops short of describing rate limits or failure modes, so not a full 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 purpose and the key alternative, and the operation list earns its place. The second sentence re-states the zabbix_write routing already given in the first, which is mild redundancy but not bloat.

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 correctly carries the return contract (plan identifier plus apply command) and the when/when-not guidance. Combined with 100% schema coverage and clear annotations, an agent has what it needs to call this correctly; only minor operational detail (error handling, plan expiry) is absent.

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 parameters are already documented, and the operation list in the description mirrors the schema enum rather than adding new meaning. The schema itself notes an unusual discovery affordance (passing an unknown param to learn accepted ones), leaving the description little to contribute. Baseline 3.

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 ('Describe a change to Zabbix without making it') and immediately differentiates from the two relevant siblings, zabbix_write and zabbix_plan_status. The operation enumeration further pins down scope, so an agent can identify this tool without opening its 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?

Explicit when-to-use ('before anything is written'), when-to-use-something-else ('call zabbix_write instead when the user wants the change applied now'), and how to check an existing plan ('call zabbix_plan_status'). Routing to alternatives is spelled out rather than inferred.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by naming the possible result states (waiting/applied/expired), which tells the agent this is a non-blocking, pollable status check. It stops short of noting polling cadence or expiry semantics, keeping it at a 4.

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 purpose and state enumeration before the routing advice. Every sentence carries routing or outcome information; only minor tightening is possible.

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 domain of return values (waiting, applied, expired), which is the key missing piece an agent would otherwise have to guess. For a single-parameter read tool with strong annotations, this is essentially 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?

Schema description coverage is 100% and the single plan_id parameter is documented as the identifier returned by zabbix_plan_create. The description adds no format or syntax detail beyond the schema, so the 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 (check) and resource (stored plan) and enumerates the three outcomes it distinguishes: waiting, applied, expired. It also names the sibling tools it must not be confused with (zabbix_plan_create, zabbix_write), so an agent can route correctly 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 explicit when-to-use conditions: when the user asks what happened to a change they were asked to approve, or after zabbix_plan_create while waiting. It also contrasts the two alternatives by purpose (describe a change vs. make it now), which is exactly the routing information 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 declare readOnly, idempotent, openWorld and non-destructive, so safety behavior is covered. The description adds value beyond them by disclosing which fields are returned (host, severity, state) and by scoping results to *active* problems, implying resolved events are not returned. It does not say what happens when the event id is unknown or refers to a non-problem event.

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 filler. The core operation is front-loaded in the first line and the routing guidance follows immediately.

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 is no output schema, and the description compensates by naming the returned fields, which is what an agent needs to decide whether to call it. It leaves the not-found / non-problem-event behavior unspecified, a minor gap for a single-param read tool whose annotations already carry the safety profile.

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% for the single 'event' parameter, so the schema already documents it with a type and an example. The description only restates it as 'event identifier' and adds no format, encoding, or lookup constraints beyond that. 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?

States a specific verb (Show), resource (one active problem) and scope (by event identifier), and explicitly contrasts with the sibling zabbix_problems which returns the list. An agent can distinguish it from every sibling without opening a 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 an explicit trigger condition ('the user gives one event identifier and wants that problem's host, severity and state') and names two alternatives with the condition that selects each: zabbix_problems for what is broken now, zabbix_alert_why for notification delivery questions.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: suppressed problems are returned by default and annotate which maintenance window hides them, and truncation is reported. It stops short of describing return fields or pagination, but the default-suppression disclosure is exactly the kind of non-obvious behavior an agent needs.

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-loads the core action and ordering, then behavior, then routing. The rationale sentence ('Hiding them silently is how an outage goes unnoticed for weeks') is editorial but earns its place by justifying the default-include behavior; the only minor cost is a slightly chatty tone.

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 parameters at full schema coverage, no output schema, and the description still covers the surprising default (suppressed included) and correct sibling routing. It omits any hint of what a returned problem record looks like and nothing about pagination beyond the schema's truncation note, but for a read-only list tool that is a minor 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 100%, so all seven parameters already carry their own meaning. The description adds only an implicit tie to exclude_suppressed via the 'included by default' statement; it offers no extra format, matching, or severity-scale detail 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 ('List active Zabbix problems') plus an ordering guarantee ('newest first') that no sibling provides. It also explicitly distinguishes itself from zabbix_problem (single event identifier) and zabbix_alert_why (missing notification), so an agent can route without opening schemas.

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 concrete invocation triggers ('what is broken right now', 'which problems are firing', 'whether anything is in alarm') and names two alternative tools with the conditions that select them. Both the when-to-use and the when-to-use-something-else cases are covered.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds non-obvious context the annotations cannot: why the tool exists (identifiers only exist inside the message text, so 'acknowledge that one' is unactionable without it). It does not describe behavior on unparseable input or the shape of the extracted identifiers.

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 paragraphs: definition first, then the rationale for the tool's existence, then the usage condition and next steps. Front-loaded and every sentence carries distinct information; no 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 a one-parameter read-only parser with no output schema, the description conveys the input contract, the reason for the tool, and the follow-on routing. The main remaining gap is that it never states what comes back when the text contains no identifiers, which matters since there is no output schema to consult.

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% and the property description already covers the single parameter, so the baseline is 3. The description adds meaning by clarifying the tolerated input forms — a notification pasted out of a chat client, or a bare event identifier — which broadens the accepted value beyond a strict notification blob.

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: turning notification text into event, host, and trigger identifiers. It also explains the distinguishing role versus siblings by naming zabbix_problem and zabbix_alert_why as the follow-on tools, so an agent can tell this is a parsing/normalization step, not a query.

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 says when to use it (user pastes a notification from chat and the identifier is buried in the text) and names the downstream tools to call once the event identifier is extracted. No when-not guidance for malformed or non-notification input, which keeps it 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 already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that: availability is derived from the interface rather than host.available (removed in 5.4), and results exclude hosts with silent items. It does not describe the result shape or ordering, which keeps 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?

Front-loaded with the core purpose in one line, then usage, then exclusions. Each sentence is doing work, though the 'code still reading it sees nothing at all' remark is aimed more at maintainers than at the calling agent and is slightly surplus.

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 single-filter list tool with no output schema, the description covers purpose, scope, the availability semantics, and sibling routing. It stops short of describing what each returned row contains (host, interface type, error), a minor gap given no output schema exists.

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?

Only one optional parameter (limit) and schema description coverage is 100%, including the truncation-reporting behavior, so the schema carries the full burden. The description adds no parameter-level detail, which is the expected baseline here.

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 gives a precise verb and resource ('List monitored hosts Zabbix currently cannot poll') and the scope is unambiguous. The third paragraph further distinguishes it from zabbix_host_investigate and zabbix_metrics_latest by naming the condition under which those siblings apply instead.

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 states when to use it ('which hosts Zabbix cannot poll, or which agent, SNMP, IPMI or JMX interfaces are down') and, critically, when not to ('a host whose interface is up but whose items went silent is not listed here'), routing that case to zabbix_host_investigate.

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 destructiveHint=true, readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the safety envelope is partly covered; the description still adds real value by stating destructive operations remove something 'Zabbix cannot restore on its own', flagging which individual operations are destructive, and disclosing the audit-log side effect. It does not discuss idempotency/retry behavior, which is the remaining gap.

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 routing sentence, then the operation list where every line carries distinct information and destructive markers. It is long, but the length is justified by eight operations; only minor trimming (e.g. the closing 'say plainly what you did' aside) would be possible without losing meaning.

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 multi-operation write tool with no output schema, the description covers selection, alternatives, destructive semantics, and audit behavior. It does not describe what a successful call returns or how failures are reported, a minor omission given there is no output schema to fall back on.

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% (baseline 3), but the description goes further by enumerating all eight operations with one-line semantics, so the agent knows what each enum value actually does. It also explains the freeform 'params' escape hatch from the schema description. Marginal but genuine value 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?

Opens with a specific verb+resource ('Change Zabbix in one call and record it in the audit log') and immediately separates itself from sibling tools by name (zabbix_plan_create, zabbix_plan_status). An agent can tell this is the write/execute path versus the plan/dry-run path 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?

Explicitly states when to use it ('user wants a permitted change applied now rather than only described'), names the two alternatives with their own triggering conditions, and adds the routing heuristic 'prefer the narrowest operation that does the job'. Nothing is left to inference.

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