playlist_rotate

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

No annotations are provided, so the description carries the disclosure burden. I adds real behavioral context — 'Written as one atomic replace' discloses atomicity and the quota line '2 GETs + 1 PUT' discloses a mutating write path — but it never explicitly states that the operation modifies the playlist or that dry_run defaults to true to avoid changes.

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 sentences, each earning its place: core semantics, implementation note, and cost. The rotation behavior is front-loaded and there is zero filler.

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 5-paramder tool with a 100%-documented schema and no output schema, the description covers the key gaps: rotation math, atomicity, and quota. Nothing essential is missing, though it could have referenced the dry_run plan workflow or the rotate_playl_plan sibling given the read-first mutation pattern.

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 100%, so the baseline is 3. The description mostly restates what the positions schema already says, adding only the 'wraps around' nuance; it does not materially extend the paramter meaning.

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 with precise, unambiguous semantics: 'Rotate a playlist by N positions' with exact direction behavior for positive and negative N including wrap-around. The behavior is defined well enough to distinguish from rotation-related sibling tools, though it does not explicitly name any sibling (e.g., rotate_playlist_plan, playlist_reverse) to rule out confusion.

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 gives no when-to-use or when-not-to-use guidance and does not reference alternatives like rotate_playlist_plan or reorder_playlist items. The quota and atomic-replace notes imply cost context, but nothing tells an agent when this tool beats another.

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