Cancel job

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

The destructiveHint=true annotation already signals this is a mutating operation, and 'Cancel' is consistent with that. However, the description adds nothing beyond the annotation: it doesn't say whether cancellation is graceful or forced, whether partial build artifacts are left behind, whether it blocks until the job stops, or what error occurs if the job has already finished. For a destructive one-param tool that is a meaningful gap.

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?

A single front-loaded sentence with no filler, which is good structurally. But the brevity is under-specification rather than efficiency, since key facts about the id and cancellation semantics are absent.

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?

This is a destructive, no-output-schema tool with an undocumented required parameter and no stated post-conditions. Given the siblings include job_status and gradle_run, a caller needs to know how the id is obtained and what state the job ends in. The definition leaves both unaddressed.

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?

There is one required parameter 'id' with 0% schema description coverage, so the description carries the full burden of explaining it. It never states that the id is a job identifier, where that id comes from (presumably a prior job_status or gradle_run response), or its format. This is exactly the case where the description should compensate and does not.

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 (cancel) and resource (background job), and the qualifier 'running' implies the target is an active job rather than a completed one. It is distinguishable from the sibling job_status, which inspects rather than terminates jobs. Slightly short of a 5 because it doesn't clarify what a 'job' is in this environment (build? gradle task?).

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?

No guidance on when to cancel versus waiting for completion, and no mention of checking job_status first to confirm the job is still running. The sibling job_status is the obvious companion tool but is never referenced. The agent must infer the workflow.

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