tvh_apply_maintenance_plan

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

The description adds substantial behavioral context beyond the annotations: plans expire after 15 minutes, real executions consume the plan ID, stale or invented plans are rejected, active inputs/subscriptions cause refusal, inventory and node fields are rechecked, and guarded rollback is attempted on partial failure. It also warns that this is not an atomic transaction or full backup and instructs the caller to keep the recovery_snapshot. These details are consistent with the destructive and non-idempotent 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 compact and front-loaded, starting with the core action and default preview behavior. The second paragraph is dense with relevant operational constraints and contains no wasted sentences.

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 destructive, non-idempotent mutation tool, the description covers the critical safety and operational behaviors: expiry, ID consumption, validation, refusal conditions, rollback behavior, and snapshot retention. An output schema exists, so return values need not be explained in detail, and the description still highlights the key recovery artifact.

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 description coverage at 0%, the description carries most of the parameter semantics. It explains the origin, expiry, one-time use, and rejection conditions for plan_id. It also implies the dry_run default and contrast between preview and actual execution, though it does not explicitly name the dry_run parameter.

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: apply a reviewed maintenance plan from this MCP process. It also distinguishes preview versus execution through the default dry-run behavior. It does not explicitly name sibling planning tools or alternatives, so it falls short of full sibling differentiation.

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 implies usage by referring to previously reviewed plans and stating that previews happen by default. It also explains execution semantics such as ID consumption and stale-plan rejection. However, it does not explicitly say when to use this tool versus alternatives such as restore_snapshot or the planning tools, and it does not name exclusions beyond runtime refusal conditions.

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