ae_setCompSettings

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

Annotations already declare it is a non-readonly, non-destructive, closed-world operation, so safety baseline is covered. The description adds the field list but omits the important consequence that resizing/duration changes can affect layers and keyframes, and doesn't say changes are undoable or require the comp to be unlocked.

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?

A single front-loaded sentence with the verb and field list up front and no filler. Dense but appropriately sized for a 14-parameter tool.

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?

With 14 optional parameters, low schema coverage, and no output schema, the description should clarify units, which comp is targeted, and side effects of changes. It provides only a field roster, leaving an agent under-equipped to call a mutation tool safely.

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 only 14%, so the description must compensate but largely just renames fields. Units and formats (duration in seconds, pixelAspect ratio, workAreaStart units, and especially the two-element resolutionFactor array, which is loosely paraphrased as 'preserve resolution') are left ambiguous.

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 ('change') and resource ('comp settings') and enumerates the editable fields, so an agent knows exactly what this mutates. It doesn't explicitly name a sibling to route away from, so it stops short of a 5.

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?

There is no guidance on when to use this versus ae_createComp, ae_getCompState, or ae_setTransform. Nothing states prerequisites, whether an existing comp is targeted, or how omitted fields are treated.

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