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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description goes beyond them with real behavioral facts: all-or-nothing when any track id is missing, duplicates are re-added rather than deduped, order is preserved, and the Music app is launched if closed. It stops short of covering permissions (Music automation consent) or failure modes when a playlist name is absent and create=false.

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?

Five short sentences, each carrying a distinct behavioral fact (ordering, refusals, atomicity, duplicates, app launch), with the core action front-loaded. No filler or restatement 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?

For a destructive mutation with an output schema present, the description covers the risky semantics well (atomicity, duplicate behavior, refused playlist types). Minor gaps: no mention of the permissions needed to control the Music app and no statement of what happens when the playlist does not exist and create=false.

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%, so baseline would be 3, but the description adds genuine meaning: 'in the order given' clarifies that track_ids order is preserved, and 'a track already in the playlist is added again' clarifies that no dedupe occurs against playlist contents. The 'create' flag's absent-playlist behavior is left to the schema.

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?

States a specific verb and resource ('Adds library tracks to a playlist of the Music app') and narrows scope with 'library tracks' and 'in the order given'. The refusal sentence (smart playlists, folders, app-managed playlists) further distinguishes it from music_list_playlists and music_search_library, which only read data.

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 context is implied rather than stated: the description tells you what it refuses and that it opens the Music app, but never says when to call this versus music_list_playlists or music_search_library (those are only named inside the schema). No explicit guidance on prerequisites such as needing track ids first.

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