Stop a running command

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

Goes well beyond the destructiveHint annotation by disclosing the mechanism (Ctrl-C), the three-second grace period, the fallback behavior (slot freed anyway, process left running and shown as stuck), and the data-loss consequence ("loses whatever it had not saved"). That is exactly the operational detail an agent needs before invoking a destructive stop.

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?

Three sentences, no filler: identity/scope first, then behavior with consequences, then the routing rule to the alternative. Each clause carries distinct information the agent cannot infer elsewhere.

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, non-idempotent two-parameter tool with no output schema, the definition covers what it does, the timeout/fallback path, the failure mode, data-loss risk, and the sibling alternative. Nothing an agent needs in order to call it correctly is missing.

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 both parameters are already documented, and the description's mention of the slot number largely restates the schema. It does implicitly contrast with ctrl_c_only by describing the default free-the-slot-after-timeout behavior, but it never names that parameter or explains the keep-the-slot trade-off directly.

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?

States a specific verb and resource ("Stop a command started by amiga_run") and pins down the identifier semantics ("by its slot number from amiga_slots"). It explicitly distinguishes itself from the sibling amiga_kill, so the agent can choose without opening either schema.

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?

Names the prerequisite lineage (only commands from amiga_run) and names the alternative with its selection condition: "To stop any other task use amiga_kill." Both the when-to-use and when-not-to-use cases are covered explicitly.

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