kd_setup_guest

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

With no annotations provided, the description carries the full burden and does a good job: it discloses the mutation ('Enable kernel debugging'), the mechanism ('bcdedit over SSH'), the transport alternatives, and a concrete side effect ('store the KDNET port and key in vms.yaml'). It does not mention prerequisites like SSH reachability or whether a reboot is required, but the core behavioral profile is clear.

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 efficient sentence that front-loads the main verb and resource, then provides mechanism and persistence detail in order of importance. There is no filler or repetition of schema fields.

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?

For a setup tool with no annotations and no output schema, the description covers the main action, mechanism, and persistence, but omits operational prerequisites such as the guest being reachable over SSH, whether the debugger becomes active immediately, or how this interplays with kd_setup_host/kd_attach. It is adequate for basic selection but not fully complete for a safe, correct invocation.

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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that key and port are KDNET parameters that get persisted to vms.yaml, which clarifies why the agent should care about them and how they relate to the overall setup flow. It does not add detail about the vm parameter, but the schema already describes it sufficiently.

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 names a specific action and resource: 'Enable kernel debugging in the guest' via bcdedit over SSH. The 'guest' qualifier distinguishes this from the sibling kd_setup_host, and mentioning 'serial or KDNET per kd_transport' shows the transport modes it handles. This is specific and actionable, not a tautology.

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 implies the tool is for guest-side kernel debugging setup and references kd_transport as the transport selector, but it does not explicitly say when to choose this over kd_setup_host or when not to use it. No alternative tactic or exclusion condition is given, so the agent must infer the intended context from sibling names.

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