Astra: edit the play queue

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

Annotations already set destructiveHint=true and readOnlyHint=false, but the description adds critical context: 'clear' empties the upcoming queue without stopping the current track, and the currently playing item cannot be moved or removed, returning queue_item_not_found. This goes beyond the annotation flags and helps the agent predict side effects.

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?

Four sentences, front-loaded with purpose, and every sentence carries distinct information: action semantics, param requirements, ID source, edge-case error, and alternative tool. No 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?

Despite having no output schema, the tool is a mutation with three actions, and the description covers all actionable cases: how to perform each action, the source of IDs, the sole error case, and the alternative for adding. Annotations cover safety flags, so nothing essential is missing.

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% with per-parameter descriptions, so baseline is 3. The description adds value by mapping each action to required parameters ('move' needs queueItemId and a 0-based position; 'remove' needs queueItemId) and by specifying that queueItemId comes from astra_queue, a cross-tool reference not present in 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?

The description opens with 'Reorder or trim the Astra play queue', a specific verb+resource statement, and enumerates three actions (move/remove/clear) that map to the enum. It also distinguishes itself from astra_enqueue for adding and points to astra_queue for IDs, removing ambiguity with siblings.

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?

It explicitly tells the agent when to use this tool ('Reorder or trim the play queue') and when not to: 'To add tracks instead, use astra_enqueue.' It also gives a prerequisite: 'Get queue item ids from astra_queue.' This is clear usage guidance with an alternative tool named.

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