set_arrangement_time

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

Annotations already supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds nothing about side effects worth knowing: whether moving the playhead during playback relocates audio immediately, what happens if the position exceeds song length, or whether arrangement view must be focused. Those gaps are minor but real for a state-changing transport 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?

One front-loaded purpose sentence followed by a compact bulleted parameter list; nothing is repeated and every line carries information. The structure lets an agent read the purpose and the critical unit convention in a single pass.

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?

With an output schema present, return values needn't be described, and both parameters are fully explained. The only shortfall is contextual: the tool assumes an arrangement view / arrangement context that a sibling tool (switch_to_arrangement_view) manages, and the description never states that prerequisite.

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 carries the full burden and does: 'time' is given a unit, an origin ('beats from the start of the arrangement'), and a concrete conversion example ('8.0 = bar 3 in 4/4'), which resolves an ambiguity the raw number type cannot. It also explains the otherwise opaque 'user_prompt' field as telemetry input, so an agent knows to pass the triggering prompt rather than invent one.

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 names a specific verb and resource ('Move the arrangement playhead') with the positional target, so an agent immediately knows the effect. It does not, however, distinguish itself from close siblings such as set_transport (which in most DAW tool sets also controls playback position) or switch_to_arrangement_view, leaving the boundary to inference.

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?

Usage is only implied by the purpose sentence: you call it when you need to reposition the playhead in the arrangement. There is no explicit when-to-use vs set_transport/start_playback guidance, no stated precondition (e.g. arrangement view must be active), and no exclusion of any scenario.

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