Skip to main content
Glama
DustinTrap

kvm-pilot

by DustinTrap
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

file_firmware_report

Idempotent

Files the device's firmware-currency report as a GitHub issue when its firmware registry is behind; dry-run previews the issue, and filing requires external-write approval.

Instructions

File the device's firmware-currency report as a GitHub issue when the registry is behind (MCP twin of CLI firmware-check, #189/#190). EXTERNAL WRITE — writes outside the managed device.

The read/reconcile half always runs; registry current → nothing to file, the result says so. Filing is gated as its own external_write effect (KVM_PILOT_MCP_ALLOW_EXTERNAL_WRITE + per-invocation approval); dry_run=true previews the exact issue title/body; a missing or unauthenticated gh is a graceful filed=false reason.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
repoNoGitHub repo to file in (owner/name). Defaults to kvm-pilot's own.
sourceNoFree-text provenance recorded in the issue (who/what observed the newer firmware).
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.
dry_runNoTrue previews the exact issue title/body without filing.
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. Changed5 schema fields changedv1.0.0
    • 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 / dry_run / description
      Added value: +"True previews the exact issue title/body without filing."
    • 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)."
    • addedInput schema / properties / repo / description
      Added value: +"GitHub repo to file in (owner/name). Defaults to kvm-pilot's own."
    • addedInput schema / properties / source / description
      Added value: +"Free-text provenance recorded in the issue (who/what observed the newer firmware)."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses that it is an EXTERNAL WRITE, that filing is gated behind KVM_PILOT_MCP_ALLOW_EXTERNAL_WRITE plus per-invocation approval, that dry_run previews the payload, and that a missing/unauthenticated gh yields a graceful filed=false. It also explains the idempotent 'nothing to file' path, matching idempotentHint=true.

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?

Front-loads the core action and trigger, then escalates to the EXTERNAL WRITE warning, then supplies the mechanics. Dense but every clause (gating, dry_run, failure mode) carries information an agent needs.

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?

For a no-output-schema mutation tool it covers the essentials: preconditions, approval gating, preview path, and the exact result signals ('filed=false', 'outcome=not_confirmed', 'nothing to file'). Nothing an agent needs to call it safely is missing.

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 coverage is 100% and the schema already documents each parameter richly, so the baseline is 3. The description still adds value by framing dry_run as a payload preview and confirming the confirm param's role in the external_write gating, tying the fields to the approval workflow.

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 ('File the device's firmware-currency report as a GitHub issue') plus the triggering condition ('when the registry is behind'). It also positions itself against the read half and against the CLI tool it mirrors, so an agent can distinguish it from the sibling firmware_check.

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?

Clearly explains the condition for acting ('registry current → nothing to file') and the gating/approval flow, so the agent knows the preconditions. It stops short of explicitly naming firmware_check as the read-only alternative, but since it embeds the read half itself, the routing gap is minor.

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