move_track

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

With no annotations provided, the description carries the full burden and does so well: it states 'Side effects: none — the request is validated and refused', documents the refusal return code (CAPABILITY_UNAVAILABLE with LOM/SDK evidence in details), and separates edge-case codes (INVALID_PARAMS for bad indexes, WRONG_TYPE for return/main tracks). This is exactly the behavioral disclosure an agent needs for a deliberately failing tool.

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 single most important fact (the operation is impossible) in the first clause, then labels Example / Edge cases / alternatives. No filler, and the dense structure is appropriate for a multi-faceted error contract.

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 no-op probe tool with no output schema and two bare integer parameters, the description supplies everything needed to call it correctly and interpret the result: outcome code, error differentiation, side-effect status, and workarounds. Nothing material 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 description coverage is 0%, so the description must compensate; it partially does. The example 'move_track(3, 0)' establishes that the first argument is the source track and the second the destination, and the edge cases clarify accepted value ranges. However it never states the indexing base (0- vs 1-based) or behavior when the two indexes are equal, leaving real ambiguity about parameter values.

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 ('move one track to another index') and immediately discloses the crucial fact that it cannot succeed. It implicitly differentiates itself from working tools by declaring the capability gap, but it never names the siblings that actually perform reordering (reorder_tracks, move_track_to_group), so an agent must infer that distinction.

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 clear when-to-call context (only to probe/confirm the capability gap) and offers alternatives ('Create tracks at the index you want, or reorder by hand in Live'). The weakness is that the alternatives are non-tool actions, ignoring the sibling tools reorder_tracks and move_track_to_group that would let an agent accomplish the same goal programmatically.

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