lock_track

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

With no annotations, the description carries the full behavioral burden. It discloses the dual lock/unlock mode, that locking prevents editing, and that the sequence need not be active — all genuinely useful. It does not mention return behavior, error conditions for invalid track indices, or reversibility, though the schema's 'locked' field partially implies it.

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?

Two short sentences with zero filler. The primary action is front-loaded, and the second sentence earns its place by adding the non-active sequence constraint that an agent would otherwise have to discover by trial.

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 low-complexity boolean mutation with fully documented parameters, the description plus schema cover the essentials: what it does, its effect on editing, and when it applies. Minor gaps remain around return value and error behavior, but nothing an agent needs to invoke it correctly 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 all four parameters meaningfully described, including the locked boolean semantics ('Whether to lock (true) or unlock (false)') and the sequenceId GUID source from list_sequences or get_active_sequence. The description adds no parameter-specific detail, but the schema already handles the burden, so the baseline of 3 applies.

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 action (locks or unlocks) on a specific resource (a track) with a stated behavioral effect (prevent/allow editing). This clearly distinguishes it from sibling track tools like mute_track, rename_track, and toggle_track_visibility, none of which manage edit protection.

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 first sentence makes the intended use clear: control edit protection on a track. The second sentence adds a meaningful constraint — the target sequence need not be the active one — telling an agent it can act on non-active sequences without switching first. No explicit alternatives or exclusions are named, but none of the siblings offer the same lock/unlock capability.

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