Skip to main content
Glama
Sign In
AIops-tools

xcpng-aiops

by AIops-tools
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

vm_stop

Destructive

Stop a VM via clean guest shutdown or forced hard power-off, capturing prior state. Refuses to stop the Xen Orchestra self VM to prevent API loss; dry_run previews.

Instructions

[WRITE][risk=medium] Stop a VM (clean shutdown; hard with force). Inverse: vm_start.

A clean shutdown needs the guest tools running; force maps to a hard
power-off. Captures the prior power state.

Refuses the VM declared as running Xen Orchestra (xo_self_vm_uuid on the
target) — stopping XO removes the API vm_start would travel over, so
recovery needs hypervisor console access. dry_run refuses it too: a preview
that returns green for a call that will be refused is a wrong preview. That
guard is exact and opt-in: an undeclared target is refused nothing, on
either path. The dry-run adds a weaker IP-based selfVmHint (null when there
is none) that is a coincidence to check, never a verdict and never a block —
XO's API exposes no self endpoint, so nothing here can be certain.

Args:
    vm_id: VM uuid (see vm_list).
    force: Hard power-off instead of a clean guest shutdown.
    dry_run: If True, preview without stopping (no undo recorded).
    target: Xen Orchestra target name from config; omit for the default.

Input Schema

NameRequiredDescriptionDefault
forceNo
vm_idYes
targetNo
dry_runNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds substantial extra behavior: it records the prior power state (implying an undo entry, consistent with the undo_list/undo_apply siblings), dry_run records no undo, and stopping the XO self VM is refused because it would cut the very API path needed for recovery. It also discloses that the IP-based selfVmHint is a non-blocking coincidence, not a verdict.

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

Conciseness4/5

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

Front-loads the action and its risk tag, then layers semantics, the refusal guard, and the dry-run caveat in a logical order. Most sentences earn their place, but the passage on the IP-based selfVmHint is longer than strictly needed and repeats the 'not a verdict / not a block' idea.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With four parameters, no output schema, and only coarse annotations, the description supplies the missing behavioral contract: refusal condition, undo/prior-state capture, dry-run semantics, and the force trade-off. It stops short of describing failure modes for a non-XO stop (e.g., guest tools absent) or what the return payload contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry all four parameters, and it does: vm_id (uuid, cross-referenced to vm_list), force (hard power-off vs. guest shutdown), dry_run (preview with no undo recorded), and target (XO target name from config, omit for default). This adds meaning well beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Stop a VM') and immediately qualifies the two modes (clean shutdown vs. hard power-off with force). It also explicitly names its inverse sibling, vm_start, so an agent can distinguish it from vm_reboot and vm_start without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear conditions for choosing the two paths: clean shutdown requires guest tools, force maps to hard power-off. It also explains the dry_run path and the self-VM refusal. It does not, however, contrast with vm_reboot or state when a stop is preferable to a reboot, so usage guidance is strong but not fully exhaustive.

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

Deploy Server

Other Tools