Audit Playlist Metadata

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact audit scope and curation norms (e.g., 20–30 tracks best, same-artist threshold, suspected interludes under 2:00). It reinforces the read-only nature without contradicting 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?

The English portion is front-loaded and concise, with the alternative routing in the second sentence. The Chinese section repeats some content but also adds unique details such as duration distribution, the same-artist threshold, and the 20–30 track curation guideline, so it is not pure redundancy.

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 single-parameter, read-only audit tool with strong annotations, the description is nearly complete: it tells the agent what is audited, what standards are applied, and when to use a different tool. The lack of an output schema means the return format is unspecified, but the listed audit dimensions give enough context for correct invocation and interpretation.

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 coverage is 100% and the single 'playlist' parameter is already described as '歌单名或 p.xxxx ID'. The tool description adds no additional parameter-level semantics, so the baseline of 3 applies because the schema carries the full burden.

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 names a specific verb ('audit') and resource ('playlist metadata') and enumerates concrete audit dimensions: length, artist concentration, genres, eras, duplicates, and possible interludes. It also explicitly distinguishes the tool from the sibling am_analyze_flow by routing BPM, key, energy, and transitions elsewhere, so an agent can disambiguate without opening schemas.

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 clearly states when to use this tool: for metadata-layer playlist audits and curation-rule checks. It also names the alternative: 'For BPM, key, energy, and transitions, use am_analyze_flow.' This is explicit routing guidance with a condition, matching the high standard of the calibration example.

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