pdm_pve_lxc_migrate

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

With no annotations provided, the description fully discloses all relevant behaviors: it is a mutation that moves (not copies) the container, the source stops hosting, LXC lacks live migration (online=True means stop-move-start with real downtime), and the tool defaults to dry-run returning a PLAN. It also notes that pve_task_status cannot track the resulting PDM UPID, only pdm_tasks_list can. This is comprehensive and honest.

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 a single paragraph of about 100 words, yet it covers purpose, alternatives, behavioral details, parameter nuances, and tracking. Every sentence adds value and is front-loaded with the most critical info. No fluff or repetition.

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?

Given the tool's complexity (mutation, multiple parameters, PDM integration, dry-run workflow), the description is fully complete. It explains the entire lifecycle: what happens on execution (move, not copy), the effect of online vs offline, the dry-run vs confirm workflow, the result types (PLAN vs task reference), and how to monitor the task. The existence of an output schema does not detract from this.

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?

Although the input schema already covers all parameters (100% coverage), the description adds deeper context: it clarifies that 'target' must be within the same remote's cluster, explains that 'online=True' is not truly live for LXC but a restart, and specifies the dual-mode behavior of 'confirm' (false returns PLAN, true submits). This enriches the agent's understanding beyond the schema.

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 clearly states the tool's purpose: 'relocate a container to another node within the same cluster, through PDM.' It uses a specific verb (relocate/migrate) and resource (LXC container), and immediately distinguishes it from two sibling tools (pdm_pve_lxc_remote_migrate and pve_guest_migrate) by naming them 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?

The description provides explicit guidance on when to use this tool versus alternatives: for same-cluster migration via PDM, versus cross-datacenter or direct cluster migration. It also explains the behavior of the 'online' parameter, the dry-run default, and how to track the task. This gives the agent clear context for selection.

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