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

Annotations already flag destructive/non-idempotent; the description adds context that matters beyond them – HTTP 200 is only transport success, the real outcome is in exit_code/stderr/timed_out, and a lost reply must not be blindly retried. The default SYSTEM execution context hints at privilege level. Missing: what exactly is destroyed on failure or where the process runs.

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?

Telegraphic, dense sentences with zero filler and the mutually-exclusive choice front-loaded. The retry warning is high-value. The choppy phrasing sacrifices some readability but every sentence earns its place.

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 destructive no-output-schema execution tool it correctly explains how to interpret the result, which is the biggest gap filler. It still omits what the required id identifies (target machine?) and what params/stdin feed into, so an agent cannot fully construct a call from the description alone.

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 description coverage is 0% and the body is a nested oneOf, so the description must compensate. It clarifies script-vs-argv exclusivity and the desktop flag, but leaves id (required), stdin, params and timeout_s completely unexplained despite their ambiguity.

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 never states the action directly: it opens with a parameter choice ("Choose script or argv") and only the mention of exit_code, stderr and timed_out lets an agent infer that this executes code/commands. The purpose is inferable but not stated as a verb+resource, and it gives no sibling differentiation against ssh or machine_request.

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?

It gives real conditional rules: script and argv are mutually exclusive, desktop:true is required for native Office, and the default runs as SYSTEM. It offers no guidance on when to pick this over ssh or machine_request, so tool selection is left to inference.

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