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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behaviour the annotations cannot express: the cancelled outcome state and the no-op-on-completed rule, which tells the agent the call is safe to retry on any scan_id. It says nothing about permissions or what happens to partial dedup results, which keeps it at 4.

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, zero filler: the action and target come first, the edge-case behaviour second. Every clause earns its place and nothing is repeated from the schema or annotations.

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 one-parameter mutating lifecycle tool this is nearly complete: the outcome state, idempotency behaviour and return value (current status) are all stated, and annotations cover the safety profile. The only gap is provenance/validation of scan_id, which is not addressed anywhere in the definition.

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?

With a single scan_id at 0% schema description coverage, the description carries the burden and does only partly: the context makes clear it identifies the scan to cancel, and the state transitions imply which scans are valid input. It never says where scan_id comes from (list_dedup_scans / start_dedup_scan output) or what an invalid or unknown id yields.

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 first sentence names a specific verb (Отменить/cancel) and a specific resource (идущий скан дублей / an in-progress dedup scan), and adds the exact state transition pending/running → cancelled. That is enough to separate it from its sibling start_dedup_scan and from get_dedup_scan without opening any schema.

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 states the preconditions (the scan must be pending or running) and explicitly handles the negative case — on a completed scan it is a no-op and just returns the status. It does not name an alternative tool (e.g. get_dedup_scan for polling, or a delete route for removing a finished scan), so it falls short of full when/when-not/alternatives guidance.

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