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

Annotations already declare destructiveHint=false, so the description's 'nothing is deleted, it is free' reinforces rather than merely repeats. It adds genuinely new behavior: the scan runs asynchronously in the background, progress must be polled via get_dedup_scan, and specific HTTP-style error codes (404, 409) signal not-found and concurrency conflicts.

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?

Front-loaded with the action and its safety/cost profile, then parameters, then error codes — each clause adds distinct information with no filler. Parenthetical and semicolon structure keeps it dense without becoming unreadable.

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 background-start tool with no output schema, it covers everything needed to invoke it correctly and explains how to retrieve results via get_dedup_scan. The only gap is that connection_id's meaning and acceptable values are never stated directly.

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 0%, so the description carries the parameter burden and does well: scope_path is defined with the critical '' = entire disk default, and keep_rule's enum values are explained with their retention semantics. connection_id is left unexplained, though the 404 note about 'cloud not found' implicitly identifies it as the target cloud.

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 and resource (start a duplicate search in the cloud) and immediately scopes it: background execution, analysis only, nothing deleted. This distinguishes it from the sibling execute_dedup, which performs the actual action, without the agent needing to open 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?

Explicitly routes status polling to get_dedup_scan and makes clear this tool is analysis-only and free, implicitly steering destructive work to execute_dedup. It also names the two failure contexts (404 cloud not found, 409 scan/transfer already running) that tell the agent when a call cannot proceed.

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