cancel_job

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

Annotations already declare this is a non-read-only but non-destructive, closed-world mutation. The description adds real context beyond that: cancellation is a *request* (asynchronous/graceful), not an immediate kill, and the caller must poll until a terminal state. It does not say whether a running job's in-flight work is aborted or what happens if cancellation is refused, which keeps it below 5.

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?

Two short sentences, action leading and workflow guidance second. Every clause carries information; nothing is 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?

An output schema exists, so return-value detail is unnecessary. For a single-parameter async mutation the description covers the action, the applicable state scope, and the required follow-up behavior. It is only slightly short of complete in not clarifying the relationship to job_status and delete_job.

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 with 0% schema description coverage, but the tool name and description fully explain what it is: the identifier of the job being cancelled. No format, source, or lookup guidance is provided, so the description neither compensates for the coverage gap nor adds much beyond the obvious.

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 gives a specific verb and resource ('Request cancellation of a queued/running job') and scopes it to jobs in non-terminal states, which implicitly separates it from delete_job and job_status. It does not explicitly name the sibling it differs from, so an agent must infer the distinction.

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?

'queued/running job' implies the applicable condition, and the second sentence gives workflow guidance ('Poll until its state is terminal'). However, it never names job_status as the polling tool or explains when to use delete_job instead for removing a job permanently, leaving alternatives to inference.

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