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

Annotations only declare the mutation/safety profile; the description adds cost behavior ('Free (counted with the plans an hour)'), latency ('about half a minute'), billing semantics ('only the shots made again are charged, the others are reused'), and immutability of the original. It also discloses that the returned plan may include the following shot when it carries straight on, which is non-obvious behavior beyond any structured field.

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-loaded with the core action and cost, then preconditions, then post-call workflow, then the sibling contrast — a sensible ordering with little waste. Minor deductions for compressed phrasing such as 'Free (counted with the plans an hour)' and the run-on final sentence, which take a second read to parse.

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?

There is no output schema, yet the description explains what comes back (a plan whose revision names the video and the re-made shots) and what to do with it. For a 3-parameter, non-idempotent mutation tool, the preconditions, billing model, timing, and follow-up call leave nothing an agent needs 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 100%, so video_id, shot and note are already documented, and the description adds no format or constraint detail for them. It does add adjacent meaning by explaining that the shot index also pulls in the next shot when continuity requires it, but that is closer to behavioral disclosure than to parameter semantics. Baseline 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?

States a specific verb and resource ('rewrites one shot of a delivered music video from a note') and immediately scopes it against the sibling that could be confused with it: 'create_music_video makes the revision as a new video; the original never changes.' An agent can distinguish revise-in-place from create-new without opening either schema.

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 an explicit precondition ('For a music video whose revisable_until (get_video) is still ahead'), names the alternative (create_music_video) and its different outcome, and prescribes the follow-up sequence: show the rewritten shot, then quote_music_video with song_id, plan_id and quality. When-to-use, when-to-use-something-else, and next step are all present.

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