Skip to main content
Glama
DustinTrap

kvm-pilot

by DustinTrap
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

ssh_exec

Destructive

Run a shell command on a managed host over SSH to inspect or change its OS, gated by operator approval.

Instructions

Run a command on the managed host's OS over SSH. DESTRUCTIVE / in-band.

Gated by its own SSH effect gate (never the HID gate) + per-invocation approval, with typed same-path denials (#234). host overrides the profile/env ssh_host at runtime (e.g. a discovered install-time DHCP address).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
hostNoOverride the profile's ssh_host for this call only, e.g. an install-time DHCP address the profile cannot know yet.
commandYesShell command line to run on the managed host as the profile's SSH user.
confirmNoPer-invocation approval when the client cannot prompt a human: set true to approve this exact call under the operator's standing policy. Leave false when the client supports elicitation (a human is asked). Never pre-set it speculatively; a denial returns outcome=not_confirmed.
profileNoProfile name from ~/.config/kvm-pilot/config.toml selecting which KVM/BMC (and its managed host) this call targets. Omit to use the server's default (KVM_PILOT_PROFILE).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.0
    • addedInput schema / properties / command / description
      Added value: +"Shell command line to run on the managed host as the profile's SSH user."
    • addedInput schema / properties / confirm / description
      Added value: +"Per-invocation approval when the client cannot prompt a human: set true to approve this exact call under the operator's standing policy. Leave false when the client supports elicitation (a human is asked). Never pre-set it speculatively; a denial returns outcome=not_confirmed."
    • addedInput schema / properties / host / description
      Added value: +"Override the profile's ssh_host for this call only, e.g. an install-time DHCP address the profile cannot know yet."
    • addedInput schema / properties / profile / description
      Added value: +"Profile name from ~/.config/kvm-pilot/config.toml selecting which KVM/BMC (and its managed host) this call targets. Omit to use the server's default (KVM_PILOT_PROFILE)."
  2. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

Beyond the annotations (destructive, non-idempotent), it discloses that the call is gated by a dedicated SSH effect gate rather than the HID gate, requires per-invocation approval, and can return typed same-path denials. This adds real behavioral context the annotations do not carry.

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?

Short and front-loaded, leading with the core action and the DESTRUCTIVE tag. The issue-reference fragment '(#234)' and the parenthetical are somewhat cryptic and cost a little clarity.

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?

For a destructive no-output-schema tool, it covers the essential safety and approval model that an agent must know before invoking. It could say more about error/denial outcomes, but the confirm parameter's schema description already covers the not_confirmed case.

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

Parameters3/5

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

Schema coverage is 100%, so all four parameters are already documented. The description only re-explains the host override (already in the schema) and adds no semantics for command, confirm, or profile, so baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Run a command on the managed host's OS over SSH') and flags the safety profile with 'DESTRUCTIVE / in-band'. It doesn't explicitly distinguish itself from close siblings like ssh_reachable or ssh_discover, so it falls just short of a 5.

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

Usage Guidelines3/5

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

It names the gating mechanism (SSH effect gate, per-invocation approval, same-path denials), which implies the operational context, but there is no explicit when-to-use versus ssh_reachable/ssh_discover guidance or stated preconditions for the target host.

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