sylve_vm_template

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds nothing to refine that: it does not say that only 'delete' is destructive, that 'capture' creates a new artifact from a live VM, or that 'deploy' clones N VMs and is therefore the most consequential action. For a multi-action tool where the safety profile varies per action, this is a meaningful 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?

A single front-loaded sentence with zero filler. It is efficient, though the terseness leaves no room for the per-action detail the tool actually needs.

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?

This is a seven-parameter, five-action, destructive, non-idempotent tool with no output schema, and the description never explains what each action requires or returns (e.g., capture needs vm+name, deploy needs template_id+count). The per-action parameter mapping exists only as parentheticals in the schema, leaving the agent to infer the lifecycle semantics.

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 86%, so the schema already documents parameters well, including per-action applicability like 'Source VM (capture)' and 'Template ID (show/deploy/delete)'. The description adds no parameter meaning beyond that, which is the baseline 3 case.

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 resource (VM templates) and enumerates the five supported operations, so an agent immediately knows the domain. It does not distinguish itself from the parallel sibling sylve_jail_template, which manages the same lifecycle for jails.

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 guidance on when to choose this tool over sylve_jail_template or when to fall back to sylve_vm_* tools, and no prerequisites or exclusions. The only implicit routing signal is the action enum, which the schema already provides.

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