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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the perceptual-hashing mechanism, which implies approximate matching rather than byte-level comparison. It does not disclose result format, similarity threshold, or behavior on mixed file types, but the schema's note about silently ignoring files beyond 20 covers the main edge case.

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 tight sentence that front-loads the purpose before the method. The 'Duplicate Detector —' prefix slightly redundantly repeats the tool name, but there is no other wasted content, and the key discriminator (perceptual hashing) is included.

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, read-only analyze tool with a fully documented schema, the definition covers the essential context: what it does, how it does it, and the input constraints. The main gaps — return value shape and near-duplicate threshold — are minor for an analyze-category tool with no output schema and would likely be observable at runtime.

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%: the 'files' parameter already documents the 2-20 range, accepted types, and silent-ignore behavior. The description's 'batch upload' phrasing adds minor framing but no new semantic detail 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 description states a specific verb ('Identify'), a specific resource ('duplicate or near-duplicate files in a batch upload'), and the method ('perceptual hashing'). This distinguishes it from siblings like analyze_hash (plain hashing) and analyze_image_similarity (image-specific similarity) — an agent can tell what this tool does without opening the 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 phrase 'in a batch upload' implies the intended scenario (comparing a set of files at once), and the schema's 2-20 file range reinforces this. However, the description gives no explicit when-to-use vs. when-not-to-use guidance and names no alternatives, leaving the agent to infer the boundary against near-siblings like analyze_image_similarity and analyze_hash.

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