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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely useful non-obvious behavior: acknowledgement does NOT close the problem. It omits permission/auth requirements and whether repeat acknowledgements mutate existing messages, so it stops 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 one-line purpose followed by a compact Args block; no filler. The Args section slightly duplicates the schema's own titles, but the added meaning (comma-separated, source tool) justifies it.

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?

Output schema exists so return values need not be described, and annotations cover much of the safety profile. Purpose, non-closing behavior, and both parameters are addressed, leaving only auth/permission and idempotency nuance unstated.

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 0%, so the description must carry the parameter burden; it does, defining event_ids as comma-separated IDs sourced from get_problems output and message as the acknowledgement text. Both required params are explained with format and provenance, though no validation or length constraints are given.

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 (acknowledge) plus resource (Zabbix problems) and explicitly bounds scope with '(does not close them)', which cleanly separates it from any close/resolve sibling. An agent can identify the operation without 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?

Usage is only implied: the event_ids arg note '(from get_problems output)' quietly routes the agent to the get_problems sibling as a prerequisite, but there is no explicit when-to-use or when-to-prefer-alternative statement. Adequate but thin.

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 readOnlyHint and openWorldHint, so the description carries real added burden and delivers: sorting (newest-first / value high-to-low), capping with 'showing N of TOTAL' headers, folding of problems older than the ZABBIX_BRIEF_RECENT_HOURS window, and the deliberate exclusion of disabled trigger/host/item problems. These are substantive behavioral traits not derivable from 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?

Front-loaded with a one-line purpose, then organized into coherent paragraphs covering problems, categories, capping, and maintenance. Information density is high and each sentence carries weight, though the length is on the heavier side for a no-argument tool.

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 an output schema present, the description needn't explain return values, and it still fully covers what sections appear, how they are ordered and capped, what is excluded, and how to follow up on omissions. Nothing an agent needs to select or invoke 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?

The tool takes zero parameters, so the baseline is 4. The description documents configuration knobs (ZABBIX_CATEGORIES_INI, ZABBIX_BRIEF_RECENT_HOURS) that shape output, which adds meaning beyond an empty schema, though these are environment settings rather than callable arguments.

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 ('Morning patrol summary') and then enumerates exactly what it reports: active problems (Warning and above), hosts in maintenance, and one section per configured category. This clearly distinguishes it from siblings like get_problems or get_maintenance_windows, which it references as narrower alternatives.

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 implicit when-to-use context ('morning patrol summary') and explicit cross-referencing behavior: check the In Maintenance section before treating another tool's alert as a new incident, and points to get_problems(include_disabled=True) and get_maintenance_windows for the cases this tool omits. It never explicitly states when to call daily_brief versus just calling get_problems directly, so it falls short of full when/when-not framing.

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=false, so safety is covered. The description adds useful matching semantics — host is an exact-match hostname and search is a partial-name filter — but says nothing about whether values are live/refreshed, whether the search is case-sensitive, or result limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines with the purpose front-loaded and parameters immediately after. The Args block formatting is slightly mechanical 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?

An output schema exists, so return values need no explanation, and both params are documented. However, for a read tool the description omits pagination/result-size behavior and search matching details, leaving minor gaps an agent might need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it does document both parameters: host as an exact-match hostname and search as a partial name filter. It compensates well, though it does not state whether search matches are case-sensitive or on substring vs prefix.

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: 'Get current item values for a host.' The word 'current' plus 'items' for a host distinguishes it reasonably from get_hosts (inventory of hosts) and get_problems (alerts), though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus get_hosts, get_problems, or any other sibling. The only usage signal is implicit in the name and resource, so the agent must infer the routing decision on its own.

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=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no mention of result limits, pagination, or how multiple filters combine. An output schema exists, so return values needn't be explained, making 3 the right baseline.

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 a single sentence, followed by a compact Args block with no filler. The docstring section is conventional but every line conveys distinct 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?

With annotations covering safety, an output schema covering returns, and the description covering all four optional parameters, the definition is close to self-sufficient. Gaps are minor: no statement about filter combination semantics or empty-result behavior for a tool where all parameters are optional.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full parameter burden, and it does so reasonably: each of the four args gets a one-line meaning, and the tag_value/tag_name dependency is called out. It stops short of explaining the relationship between 'role' and tag_name (presumably a role-tag shorthand) or the effect of the null defaults.

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 specific verb and resource ('List Zabbix hosts') plus the two filtering axes (tag or group), so an agent immediately knows what it retrieves. It does not name or contrast any sibling such as get_host_items, but the resource is distinct enough that confusion is unlikely.

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 filter vocabulary rather than stated: there is no 'use this when...' or 'do not use for...' guidance relative to get_host_items or get_problems. The one genuinely useful constraint ('tag_value requires tag_name') is a parameter dependency, not a when-to-use rule.

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=false, and the description goes well beyond them: it explains the Active/Upcoming/Expired grouping, the precise meaning of 'Active' (inner time period vs outer active_since/active_till frame), the documented limitation that recurring windows are evaluated against the outer frame only, and the process-local timezone caveat. These are exactly the non-obvious traits an agent cannot infer from structured fields.

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 opening line is a strong front-loaded summary and the remaining paragraphs are each doing real work (grouping semantics, recurrence limitation, timezone, parameter rationale). It is on the long side, with some parenthetical detail that could be trimmed, but nothing is pure 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?

An output schema exists, so return values need not be described, and the description still supplies the interpretation needed to read them (what Active means, why recurring windows are labeled differently, what the Expired bucket is). For a read-only listing tool with one optional filter, nothing an agent needs to call it or interpret results 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 0% for the single boolean, so the description carries the burden and does: it defines include_expired, states the default (False), and explains the rationale (set_maintenance never deletes windows, so expired ones accumulate and are noise by default). That is meaning well beyond the bare boolean name.

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 ('List Zabbix maintenance windows') and immediately positions itself relative to a named sibling as 'the read counterpart to set_maintenance'. An agent can distinguish it from set_maintenance and the other read tools 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 use case with a precondition: cross-check anomalies reported by other tools before treating them as new incidents, because hosts in Active windows are being suppressed. That is a concrete when-to-use rule tied to actual sibling behavior, not implied usage.

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 read-only annotation by disclosing sorting, age annotation, capped-total reporting, default disabled-problem exclusion, and the second count query issued when the limit is reached. These are exactly the behavioral traits an agent needs to interpret results correctly. It adds substantial value over the structured 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 front-loaded with the core purpose and then structured into behavioral context and an Args block. The opening sentence and the next paragraph slightly repeat the newest-first ordering, but otherwise every sentence carries useful information. It is appropriately sized for a five-parameter tool.

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 an output schema present, the description need not explain return structures, and it correctly focuses on invocation and behavior. It covers all five optional parameters, default filtering behavior, and limit handling. Nothing material is missing for an agent to call this read-only listing 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 0%, so the description must carry all parameter meaning. It does so thoroughly: it explains min_severity values, tag filtering and the tag_value/tag_name dependency, limit flooring and count-query behavior, and include_disabled semantics. Every parameter is documented with enough detail to invoke the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: get active Zabbix problems. It also adds scope details such as newest-first ordering and disabled-problem exclusion. It does not explicitly distinguish itself from siblings like acknowledge_problem or daily_brief, so it falls 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: this is the tool for listing active problems, mirroring the Zabbix frontend Problems page. However, no explicit when-to-use or when-not guidance is given relative to alternatives such as acknowledge_problem or daily_brief. The reference to the frontend page provides modest context but not 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that it authenticates once using a cached session, that it is lightweight and performs no problem/item scanning, and it enumerates the exact return keys including degraded/error extras (detail, categories_error, read_only_error). That is unusually rich behavioral disclosure for a health probe.

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 one-line purpose, then usage triggers, then the behavioral qualifier. The return-keys paragraph is dense and long, but it is justified because no output schema exists; a slightly tighter enumeration would read better without losing 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?

With no output schema and no parameters, the description must carry the full burden of explaining the response contract — and it does, listing all stable keys plus the conditional error keys. Combined with the call-site guidance, an agent has everything needed to invoke and interpret this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify or compensate for. It correctly adds no parameter prose and instead spends its budget on behavior and return shape.

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 set and resource: report server version, Zabbix connectivity, and configured categories. The scope is further sharpened by explicitly contrasting with sibling tools ('it does NOT scan problems or items'), so an agent can tell it apart from get_problems/get_hosts 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 explicit when-to-use triggers ('at session start', 'after a tool-call timeout') and the conditions checked by the call (MCP up, version, backend reachable and authenticated, categories loaded). It also states what the tool deliberately does not do, leaving no ambiguity about routing.

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 safety (destructiveHint=false, readOnlyHint=false), but the description adds substantial context beyond them: the exact idempotency key (name+since, not the target), the silent no-op failure mode with a cross-mode caveat, and the local-server-timezone parsing of since/till. This is exactly the kind of behavioral disclosure annotations cannot carry.

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 purpose, then routes tasks with IMPORTANT markers, so a skimming agent still captures the critical idempotency and timezone caveats. It is longer than typical and the bug-reference aside (shigechika/zapi-mcp#59) adds bulk, though the content does 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?

For a 6-parameter mutation tool with an output schema, the description covers all inputs, the selection-mode exclusivity, the timezone pitfall, and the idempotency trap. Return values are handled by the output schema, so 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 0%, so the description carries the full burden and does so: it documents every parameter including formats ('%Y/%m/%d %H:%M:%S' with an example), the name-prefix behavior, the mutual exclusivity of location/hosts, and the no-per-port limitation. Nothing material is left to the schema titles.

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 ('Create a Zabbix maintenance window') and immediately distinguishes the tool from its sibling acknowledge_problem by contrasting what each does to problem notifications. An agent can differentiate it from get_maintenance_windows 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?

Explicitly states that exactly one of location/hosts must be supplied (not both, not neither) and gives the condition selecting each mode. It also names the alternative tool (acknowledge_problem) and explains when its behavior differs, so routing is unambiguous.

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