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

Annotations already state readOnly=false, idempotent=true, and destructive=false, so the description is not required to carry the full safety burden. Still, it adds almost no behavioral context beyond bare inclusion semantics: it does not explain what state is changed, how true/false values affect the video, or what the caller should expect. It does not contradict the annotations.

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 a single front-loaded sentence with no wasted words. However, it is under-specified for a three-parameter mutation tool, so its brevity reflects incompleteness rather than well-structured conciseness. It is efficient but not sufficiently informative.

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 mutation tool with three required parameters and no output schema, the description should clarify the state change and expected behavior. Annotations cover idempotency and non-destructiveness, but the description itself does not explain how kept changes the lookbook or how this tool relates to sibling operations. It is too incomplete for reliable invocation without reading the schema and relying on inference.

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 67%, with lookbook_id and piece already described in the schema. The description adds some meaning for the undocumented kept flag by framing the operation as whether a piece goes into the video, but it does not explicitly map true/false to include/exclude or add detail about the other parameters. This is adequate but thin.

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 conveys that this tool controls inclusion of a piece in the video, which roughly matches the name and title. However, it does not use a clear action verb such as set or toggle, and it omits the lookbook context present in the tool name. The purpose is inferable but vague rather than specific and differentiated.

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 gives no guidance on when to use this tool versus alternatives such as redraw_music_video_lookbook_piece or update_music_video_lookbook. It also does not mention prerequisites, sequencing, or exclusions. The agent must infer its place from the name and siblings alone.

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