Retrieve duplicates

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds one genuine piece of behavioral context - results are scoped to the authenticated user - but says nothing about pagination, result size, or how duplicates are grouped. Modest value beyond the annotations.

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?

Three short lines with the core statement front-loaded and the operation/tag metadata clearly demoted to a suffix. The opening line simply restates the title verbatim, which is mild waste, but nothing else is padded.

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 no input parameters and no output schema, the description is the only place an agent could learn the shape of the return - e.g. whether duplicates are grouped per original asset, whether the list is paginated, or how many items to expect. It covers the 'what' adequately but leaves this structural gap, so it is minimally viable rather than complete.

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?

The tool takes zero parameters and schema coverage is reported as 100%, so there is no parameter semantics for the description to carry. Baseline 4 applies; no omission or ambiguity is possible here.

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: 'Retrieve a list of duplicate assets available to the authenticated user.' That is unambiguous and clearly separable from destructructive siblings such as immich_delete_duplicates or immich_resolve_duplicates. It stops short of explicitly naming those siblings or contrasting itself with them, so it lands at 4 rather than 5.

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?

There is no when-to-use guidance and no mention of the obvious adjacent tools (resolve_duplicates, delete_duplicates, delete_duplicate). The only usage hint is the scope phrase 'available to the authenticated user,' which is a scoping remark rather than routing advice. An agent could infer the purpose from the name, but nothing in the text tells it when this is the right call versus its siblings.

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