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

Beyond the annotations, the description adds real behavioral constraints: it explicitly does not introduce audio or zoom, and it warns that "flash-safety limits apply," which is non-obvious and operationally relevant. It leaves gaps on what happens with overlapping accents and how to undo them, but with annotations already covering the mutation/destructive profile this is solid added value.

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?

Three tight sentences, front-loaded with the action and immediately followed by placement, scope, and constraints; no filler. The only slight drag is the dense clause about "measured speech, cut or supplied-track landmarks," which packs several concepts into one phrase.

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 16-parameter mutation tool with 13% schema coverage, a nested FxRegion object, four enums, and no output schema, the description covers far too little of the surface an agent needs — most notably the effect kinds and the intensity/frames tuning. The safety and scope notes are helpful, but an agent could not reliably choose a kind or set timing from this alone.

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 only 13% across 16 parameters, so the description must carry the weight — and it explains only placement (at/on), scope ("full-frame or regional treatments" for scope/region), and density. The 11-value kind enum, intensity, frames, decay_f, colour, bands, seed, count, and start/end get no explanation at all, which is a substantial shortfall for a tool this parameter-rich.

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?

"Adds short visual punctuation" gives a verb plus a vivid characterization of the resource, and the phrase "at explicit program positions or measured speech, cut or supplied-track landmarks" pins down the insertion points. The explicit exclusion "adds neither sound nor zoom" separates it from add_sfx and add_zoom. It stops short of 5 because "visual punctuation" is metaphorical and the concrete effect family (kinds like white_hit, posterize, rgb_slice) is never named.

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 implies when the tool applies — when you have explicit positions or measured landmarks such as stress, cuts, or downbeats — but never states when to prefer a sibling like add_strobe, add_color_screen, or suggest_emphasis instead. The exclusions clarify effect scope rather than routing between tools, so the agent must infer selection.

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