job_cancel

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

Annotations already declare this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds real value beyond that by noting the effect reaches the underlying renderer/transcriber process and that cancellation is "requested" rather than guaranteed immediate. It stops short of stating idempotency, error behavior for finished jobs, or how to confirm the job actually stopped.

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, and the qualifier "queued or running" sits immediately after the object it modifies. It is efficient, though the extreme brevity leaves structural room unused rather than genuinely polished.

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 simple two-parameter mutation with no output schema, the description covers purpose and blast radius but omits post-conditions an agent needs: whether the call returns immediately, whether the job remains visible in job_list, and whether a cancelled job can be retried. Adequate but with clear gaps for a state-changing tool.

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 only 50%: projectDir is documented in the schema, but jobId is a bare string with no format or source hint. The description says nothing about either parameter, so it fails to compensate for the gap or clarify where jobId comes from (job_list/job_get).

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 ("Request cancellation") and resource ("a queued or running job"), plus the scope of effect on the underlying renderer/transcriber. It is clearly distinguishable from job_list, job_get, and job_retry by implication, but never names those siblings explicitly.

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?

The phrase "queued or running" implies the applicable job states, which is useful pre-call context. However, there is no explicit when-not guidance (e.g., what to do for an already-completed job, or whether to use job_retry instead), so routing 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.