Cancel a job (free)

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

The description discloses far beyond the annotations: the graceful-shutdown-then-force-kill lifecycle, teardown of a throwaway worktree, non-resumability of cancelled jobs, cleanup_warnings for leftover paths, idempotent retry safety, and the 'free — no model call' cost profile. This aligns with and enriches readOnlyHint=false and idempotentHint=true with no contradiction.

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?

The purpose is front-loaded in the first sentence, and each subsequent sentence earns its place by covering a distinct behavioral facet: shutdown process, force-kill fallback, non-resumably, cleanup warnings, idempotency, and cost. It is dense but not bloated; only a small trim would tighten it further.

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?

With a 100%-covered schema, an output schema present, and annotations covering idempotency and destructiveness, the description still adds substantial context: lifecycle, edge cases (terminal jobs, cleanup failure), and retry safety. The only untold edge case is behavior for a genuinely unknown job id, which is a minor gap given how much is already covered.

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 100%, and the schema itself is unusually rich: job_id explains where to find it and how to recover lost ids via kimi_job_list, and workspace_root explains the MCP-roots fallback and workspace_warning behavior. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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 opening sentence states a specific verb (Cancel) and resource (a running background Kimi job), making the tool's function immediately unambiguous. It is plainly distinct from sibling tools like kimi_job_status, kimi_job_result, and kimi_job_list, none of which perform cancellation.

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 description gives clear usage context: it applies to running jobs, and the statement that already-terminal jobs are returned unchanged effectively defines when the tool adds no value. It explicitly names kimi_job_list as the recovery path for lost job ids. It stops short of an explicit when-not statement against sibling status/result tools, but cancellation is unique among the siblings, so little exclusion guidance is needed.

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