ae_add_text_animator

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

With no annotations, the description carries the full burden and does disclose real behavioral traits: the reveal is driven by a Range Selector that is animated away, mode 'out' mirrors the reveal (last units leave first), layers can be staggered, and critically 'One undo step' tells the agent the operation is a single reversible change. It omits operational behaviors like prerequisites (must text layers exist/be selected) and error handling.

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, then mechanics, then shape/mode semantics. It is dense but every clause maps to a parameter or behavior (shape, mode, offsets, stagger, undo). Slightly long, but no filler sentences.

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 13-parameter mutation tool with no annotations and no output schema, the description explains the animation semantics well but leaves gaps: it never states prerequisites (text layers must exist or be selected), what happens when none are provided, or what the call returns. Adequate but not fully complete for the tool's complexity.

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 already 92%, so the baseline is 3, but the description adds genuine meaning: it explains how 'shape' defaults differ by basedOn (rampUp for characters/words vs square for lines), what 'rampUp' vs 'square' actually do, and that offsets default to position [0,40]/opacity 0/blur 16. This contextualizes the enums and defaults beyond the raw schema text.

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 opens with a precise verb+resource ('Add a text animator reveal') and immediately distinguishes it from the alternative approach ('instead of animating Transform'). It goes further by naming the exact mechanism (Range Selector animated away) so an agent knows exactly what artifact is produced, not just that something is added.

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?

It gives clear context for when this tool is the right choice: a motion-design text reveal rather than a Transform/keyframe animation. It does not name sibling tools (e.g. ae_set_property, ae_set_keyframes) as explicit alternatives or state when-not to use it, so it stops short of full routing guidance.

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