manage_maintenance_window

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the risk profile is covered structurally. The description contributes one genuinely new behavioral fact — that create and delete are two-step operations — but it never explains that the first call is a preview returning a token, that the second call performs the change, or what happens to hosts already in maintenance, leaving the workflow half-disclosed.

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

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

Two short sentences, front-loaded with the operation enumeration, with no filler. It is efficient but borders on cryptic: 'two-step' is compressed to the point that an agent must consult the schema to learn what the steps are.

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-parameter, destructive, non-idempotent mutation tool with no output schema and only 73% schema coverage, the description is far too thin. It omits the preview/confirm mechanics, the effect of delete (whether windows are permanently gone), and the semantics of scheduling offsets — exactly the context an agent needs before invoking a destructive write.

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?

With schema coverage at 73% across 11 parameters, the schema does most of the documentation work, including per-operation hints on name, hosts, groups, maintenanceids, active_only and confirm_token. The description adds nothing parameter-specific — notably it never connects 'two-step' to confirm_token, and it is silent on duration_minutes, start_in_minutes and data_collection, which carry no per-field descriptions.

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 names the resource (maintenance windows) and enumerates the three actions (list, schedule/create, remove/delete), which lets an agent distinguish it from every sibling tool since none of them touch maintenance windows. It loses a point for terminology drift: the description says 'schedule' and 'remove' while the operation enum uses 'create' and 'delete', forcing a small mapping step.

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 enumerated operations rather than stated as conditions — the agent must infer that 'list' is for inspection and 'create'/'delete' are for mutation. There is no guidance on prerequisites (host/group existence), on when a maintenance window is preferable to acknowledging problems, or on any exclusion relative to sibling tools such as zabbix_hosts or acknowledge_problem.

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