find_duplicates

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

No annotations are supplied, so the description carries the full burden. It does disclose useful behavior: the result includes which playlists each duplicate appears in and the IDs, and that 'limit' caps rows per list with a hard maximum of 500. It never states that the operation is read-only/non-mutating, nor how results are ordered or paginated beyond the limit, which is a meaningful gap for an unannotated tool.

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 core definition, followed by a compact per-argument breakdown; every sentence adds information and there is no filler or repetition 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?

An output schema exists, so return values need not be spelled out, and all three parameters are addressed. What is missing is behavioral framing around a read-only scan (safety profile, and any guidance on how it relates to sibling analysis tools), which is the main thing an agent would still need.

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%, and the description is what makes the arguments usable: 'playlists' accepts names, IDs or links and defaults to all loaded playlists, and 'limit' documents the 50 default and 500 maximum that the schema omits. Most importantly, the allowed values of 'kind' ('all', 'exact', 'versions') appear only in the description, since the schema declares it as an unconstrained string; this is close to essential and only slightly under-specified about the default value of each mode.

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 gives a specific verb and resource ('Duplicates among the loaded playlists') and immediately splits the result into two well-defined categories, exact ID duplicates and same song/artist under different IDs. That level of detail lets an agent distinguish it from siblings like compare_playlists or group_tracks 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?

Usage is only implied: the 'playlists' default of 'all loaded playlists' plus the optional scoping to 'only the ones given' tells an agent how to narrow the search, and 'kind' selects a mode. However, there is no explicit when-to-use vs alternatives such as compare_playlists or find_tracks, and no stated prerequisites (e.g., playlists must be loaded first).

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