Astra: add a target to the queue

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

The annotations mark the tool as non-read-only, non-idempotent, and non-destructive, but the description adds valuable behavioral details: it is non-interrupting, refs are opaque signed strings that must be passed through verbatim, and a stale ref can return 404. This goes beyond the annotations by explaining the opaque ref protocol and failure mode, giving the agent important operational guidance.

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 three sentences, front-loaded with the core action and key benefit, followed by parameter-specific guidance and ref handling. Every sentence earns its place, with no redundancy or fluff. It is concise yet information-dense, ideal for quick comprehension by an agent.

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 two-parameter queue-addition tool with no output schema, the description fully covers what the tool does, how to use each parameter, how to handle refs, and the potential 404 error. Combined with the annotations, an agent has complete information to select and invoke the tool correctly without ambiguity.

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 already covers both parameters with 100% description coverage, including the enum for position and a detailed explanation for targetRef. The description adds semantic richness by clarifying that the ref can represent a track, album, artist, or playlist, and by explaining how 'next' vs 'end' affects playback order. This enriches the schema's baseline and helps the agent understand the domain 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?

The description opens with a specific verb and resource: 'Add a track, album, artist, or playlist to the Astra queue.' It also differentiates from siblings by noting 'without interrupting what is playing,' which clearly distinguishes it from immediate-play tools like astra_play. The purpose is unambiguous and directly tied to the tool name.

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 provides clear context for when to use the tool (to add to the queue without interrupting current playback) and gives explicit positional guidance: 'Use position "next" to play it after the current track, or "end" to append.' It does not explicitly name alternative tools (e.g., astra_play), but the phrase 'without interrupting what is playing' implies the alternative is immediate playback. This is clear context without explicit exclusions.

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