playlist_difference_plan

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

No annotations are provided, so the description carries the full burden. It discloses the destructive commit behavior ('atomically overwrites the target'), the read-only default, and the quota ('≤7 GETs + 1 PUT when committing'). It does not explicitly state that the base and subtrahend playlists are never modified, which would round out the safety picture, but the disclosed traits already exceed what annotations would have provided.

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 sentences, each earning its place: the operation definition, the plan-vs-commit modes, and the quota. The core semantics are front-loaded in sentence one, and there is zero filler or repetition of schema content.

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 description covers the operation, both execution modes, commit conditions, and quota. With no output schema, it even nods to the return type ('returns the PLAN'). Minor gaps remain for edge cases (nonexistent playlists, empty results), but for a plan/commit tool with fully self-documenting params, this is a complete definition.

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%, putting the baseline at 3. The description adds genuinely useful cross-parameter semantics: it maps base_playlist_id to 'survivors', subtrahend_playlist_ids to 'removed', and the interaction between target_playlist_id and dry_run ('with target_playlist_id and dry_run=false it commites'). This relationship-level meaning is valuable beyond the individual schema entries.

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 states a specific verb+resource: 'Plan (and optionally commit) the set difference base minus subtrahends' with the exact semantics spelled out ('keep the base playlist's tracks that appear in NONE of up to 5 others'). It distinguishes itself from sibling mutation tools by framing it as a plan-first operation with an optional commit, and the 'base minus subtrahends' formula leaves no ambiguity about what the tool does.

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?

Clear context is given for the two invocation modes: 'Without a target it returns the PLAN read-only; with target_playlist_id and dry_run=false it atomically overwrites the target.' This precisely states when to preview vs commit. However, it does not name alternatives (e.g. playlist_subtract, playlist_diff) or give exclusion conditions, so it stops short of a 5.

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