Cancel a Harness run

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial non-obvious behavior: cancellation is a request rather than a guaranteed stop, cancelRequested is only an acknowledgement, pending Inbox is preserved, and subagent termination depends on parent-managed vs independent sessions. It stops short of describing what destructive state change actually occurs to the run.

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?

Four sentences, front-loaded with the core action, and each sentence carries distinct behavioral information. The dense internal jargon ('native history', 'reconciled terminal cancelled state') adds reading cost but not padding.

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, idempotent mutation tool with no output schema, the description covers runtime semantics well but leaves both parameters, especially idempotencyKey, undocumented and gives no hint of what the acknowledgement response contains. It is adequate on behavior and thin on invocation detail.

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%, so the description must carry the burden for both parameters. It says nothing about runId (format, constraints) and never mentions idempotencyKey at all, despite discussing acknowledgement and repeat-request semantics where the key would be directly relevant. The description does not compensate for the coverage gap.

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 states a specific action on a specific resource ('Request cancellation through the public Host API') and the title names the target ('Cancel a Harness run'). It is distinguishable from siblings like close_run_terminals or stop_service by scoping it to a run's cancellation request. It loses a point because the object of cancellation ('run') is only implied by the title, not the description text.

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?

There is no explicit when-to-use or when-not-to-use guidance relative to siblings such as close_run_terminals or stop_service. It does imply a usage stance by warning that the acknowledgement is not proof of stopping and pointing to native history inspection as the verification path. This is implied guidance rather than a clear decision rule.

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