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

Annotations declare it is a non-read, non-idempotent, non-destructive mutation, but the description adds real substance: it acts only on the explicit project_id (never the active-project pointer) and returns the project identity with its result. It also discloses that position/level/fit are preserved, which tells the agent the edit is a targeted swap rather than a rebuild.

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?

Front-loads the project scoping constraint, then the operation, then input provenance — every sentence carries information. Slightly dense with the parenthetical asides and emphatic caps, but nothing is 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 3-required-param mutation tool with no output schema, the description covers the mutation semantics, preservation guarantees, required scope, and input sources, and notes the return shape (project identity). Only minor gaps remain, such as failure behavior when the referenced music item does not exist.

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 only 33% (project_id is the only documented property), so the description must compensate — and it does: id is sourced from get_edl, storage_key follows the same convention as add_music, and project_id is explicitly required and immutable-scoped. This meaningfully fills the gaps left by the bare schema for the two undocumented parameters.

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 (Replace) and resource scope (the TRACK of an existing music item), and contrasts with the siblings that add or fit music by naming the invariant that is preserved (position, level, fit). The quoted user-intent phrase 'use a different song' makes the tool's niche instantly identifiable among add_music, set_music_fit, and swap_music.

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?

Gives a clear selecting condition ('use a different song' rather than adding or removing a music item) and anchors inputs to other tools (id from get_edl, storage_key as for add_music). It stops short of explicitly stating when NOT to use it (e.g. no music item exists yet → use add_music).

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