vmware-knight

vm_guest_download

Download a file from a VM to a local path, with optional overwrite control. Requires VMware Tools running in the guest OS.

Instructions

[WRITE] Download a file from a VM and write it to a local path.

Reads from the guest, writes the local filesystem — the write is why this is not a read tool. Returns a status string. Requires VMware Tools running in the guest OS. Use vm_guest_upload for the reverse direction; to capture command output use vm_guest_exec_output instead — it redirects and downloads for you.

Refuses a destination that already exists unless overwrite=True, and never writes through a symlink or over a directory. Pick a path that does not exist yet rather than passing overwrite=True by default.

Input Schema

TableJSON Schema

Name	Required	Description
`target`	No	Optional vCenter/ESXi target name from config.
`vm_name`	Yes	Target VM name.
`password`	No	Guest OS password.
`username`	Yes	Guest OS account to run as. Required — there is no default, so a call can never act as root without choosing root.
`overwrite`	No	True replaces an existing file at local_path (default False).
`guest_path`	Yes	File path inside the guest to download.
`local_path`	Yes	Local destination path, including the file name.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.12.10Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description goes well beyond annotations: it discloses the local-filesystem write side effect, the refusal of existing destinations unless overwrite=True, refusal to write through symlinks or over directories, and the fact that it returns a status string. This matches the annotations (readOnlyHint=false) and adds meaningful behavioral detail.

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

Conciseness5/5

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

The description is front-loaded with a one-line purpose and a [WRITE] marker, then groups alternatives, prerequisites, and safety semantics. Every sentence earns its place; there is no filler or redundancy.

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

Completeness5/5

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

The description covers operation, direction, prerequisites, alternatives, return type, and important safety constraints. Combined with the schema and annotations, an agent has everything needed to invoke the tool correctly. An output schema exists, so detailed return-value documentation is not required here.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds valuable semantics for local_path and overwrite by explaining refusal behavior, symlink/directory handling, and recommending a non-existent destination rather than overwrite=True by default. This exceeds the baseline for high schema coverage.

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?

The description states a specific verb and resource: 'Download a file from a VM and write it to a local path.' It also explicitly contrasts itself with vm_guest_upload and vm_guest_exec_output, so an agent can distinguish this tool from nearby siblings without inspecting schemas.

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

Usage Guidelines5/5

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

It gives clear when-to-use context by naming vm_guest_upload as the reverse direction and vm_guest_exec_output for capturing command output. It also states a prerequisite ('Requires VMware Tools running in the guest OS') and advises against defaulting to overwrite=True, giving actionable selection and invocation guidance.

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

Deploy Server