start_resource_maintenance

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

Annotations only signal readOnly/destructive/idempotent hints, so the description carries the burden — and it delivers: preview-vs-execute behavior, full return semantics ("confirmed (true / false / null when the after-state could not be read — null is unknown, not failure)"), state transitions ("the resource returns to its prior state when it expires"), and the undo edge case ("recorded only when the resource was known not to be in maintenance before"). The [WRITE] prefix aligns with readOnlyHint=false and the revert-on-expiry behavior aligns with destructiveHint=false; no contradiction.

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 purpose is front-loaded and every sentence earns its place — there is no filler or repetition. However, ~120 words of dense prose covering three modes, return fields, preview semantics, and undo edge cases arrive as a single unbroken block; light segmentation would improve parseability. Efficient, but slightly over-packed.

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 fully compensates by explaining the return payload (before/after states, confirmed semantics, note). All three parameter modes, the default preview behavior, the undo path via the named sibling, and the human-factors risk ("easy to forget, so prefer a window") are covered — nothing an agent needs to invoke this tool correctly or safely 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% and the schema already documents mutual exclusion, the confirmed preview flag, the epoch-milliseconds unit, and the 1-525600 range, so the baseline is 3. The description adds genuine value by mapping parameter combinations to resulting states — timed window yields MAINTAINED with auto-return, omitting both yields MAINTAINED_MANUAL that persists — which is a mental model absent from the schema. The increment is real but modest given the schema's own thoroughness.

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 clause "Put one resource in maintenance so Aria stops alerting on it and collecting its data" states a specific verb, the resource acted on, and the observable effect, going beyond a generic phrase like 'start maintenance.' The concrete scenario "use before planned work such as powering a VM or host off" grounds it, and the named states (MAINTAINED vs MAINTAINED_MANUAL) implicitly distinguish it from the paired sibling end_resource_maintenance.

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 gives an explicit when-to-use rule ("use before planned work such as powering a VM or host off") and prescriptive parameter selection: "Pass duration_minutes OR end_time_ms... Pass neither for manual maintenance" with a clear recommendation ("easy to forget, so prefer a window"). It names the alternative tool outright ("Undo: end_resource_maintenance") and discloses the safe preview path ("Default confirmed=False returns a preview without connecting"), leaving nothing to inference.

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