Add Tracks to Playlist

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

Annotations already indicate this is a non-read-only, non-idempotent write, but the description adds meaningful behavior beyond that: it is an append operation, dry_run previews matching, and Apple enforces client-ownership for writes. This gives the agent important operational context not available from the structured fields alone.

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 description is short, front-loaded with the core operation, and every sentence earns its place: the append action, the dry-run guidance, the create-playlist alternative, and the Apple ownership limitation. There is no filler or redundant restating of the title.

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?

The core selection and invocation details are covered: target playlist scope, preview behavior, and the alternative for creating a playlist. However, there is no output schema, and the description does not explain return values, the role of isrcs, or the prerequisite relationship with am_resolve_candidates. These gaps are not fatal, but they leave some call decisions to inference.

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 schema documents tracks, playlist, and storefront, while the description adds useful meaning for dry_run. However, the isrcs parameter is completely unexplained, and the phrase 'resolved tracks' is not reconciled with the schema's 'song name - artist' format. With 60% schema coverage, the description helps but leaves a noticeable gap.

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 opens with a specific verb ('Append') plus a clear resource ('existing playlist created by this API client'). It also distinguishes itself from am_create_playlist, which is the main ambiguity among siblings. An agent can quickly tell what this tool does and which sibling it is not.

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 explicitly tells the agent when dry_run=true should be used ('preview matching') and names the alternative for creating a new playlist ('use am_create_playlist for a new playlist'). The Apple ownership restriction also clarifies when this tool should not be used: playlists not created by this API client cannot be modified.

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