Request cancellation of a specific download batch to stop later groups; optionally cancel the current task after worker verification. A canceling status does not confirm the batch has stopped.
持久化请求取消指定批次，立即停止后续分组；cancel_current默认false，当前任务自然完成后取消批次，true则由worker核对身份后发送取消信号。返回canceling不代表已停止。
| Name | Required | Description | Default |
|---|---|---|---|
| batch_id | Yes | 必填，必须与当前批次一致，防止操作错批次 | |
| cancel_current | No |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds real behavioral context beyond them: the request is persisted, only subsequent groups stop immediately, and critically '返回canceling不代表已停止' — a returned 'canceling' status is not proof of actual stoppage. That caveat is exactly the kind of async nuance annotations cannot convey.
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 dense sentences ordered well: action and effect first, parameter semantics second, then the return-value caveat last. Every clause carries information; no filler or restatement of the tool name.
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, asynchronous mutation with no output schema, the description covers what is affected, that the request is persisted rather than instantaneous, and how to interpret the immediate return. Minor gaps remain: no mention of permissions, of whether a cancelled batch can be resumed via tnd_retry_batch, or of how to confirm the batch actually stopped (presumably tnd_get_batch_status).
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%: batch_id is documented in the schema, while cancel_current has no schema description. The description compensates fully by explaining its default (false) and the distinct behavior of each value. It does not explain the batch_id-must-match constraint in prose, but the schema already covers that.
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 verb and resource: '持久化请求取消指定批次' (persistently request cancellation of the specified batch), plus the scope of effect ('立即停止后续分组'). This clearly distinguishes it from read-oriented siblings such as tnd_get_batch_status and the counterpart tnd_retry_batch, though it 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?
Guidance is limited to the cancel_current choice (false = let the current task finish naturally, true = worker sends a cancel signal after verifying identity). That is useful, but it is essentially parameter-level guidance. Nothing says when to prefer this tool over checking status first with tnd_get_batch_status or when to follow up with tnd_retry_batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.