ae_addCamera

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds useful context about the camera features (one-node, depth of field), but does not cover side effects such as whether the new camera is selected, whether it affects the active comp, or undo behavior.

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 that identifies the tool and then efficiently lists the optional feature groups. No wasted words; every clause adds information.

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 10 parameters and no output schema, the description covers the main operations and feature flags. It leaves minor gaps such as default values or coordinate-space details, but it is sufficient for an agent familiar with After Effects to invoke the tool correctly.

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 10%, so the description must compensate. It successfully explains the meaning of most parameters: focal length presets in mm, position/pointOfInterest, oneNode (no POI), and depth-of-field fields (focusDistance, aperture, blurLevel). It omits type and format details (e.g., coordinate array shape, aperture units) and does not mention 'name', but the overall coverage is strong.

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 states a specific verb and resource ('add a 3D camera') within After Effects, and clearly distinguishes it from siblings such as 'ae_cameraMove' and 'ae_addLight' by naming the exact operation and its optional features.

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?

Usage is implied by the tool name and description: it adds a camera with optional presets. However, there is no explicit guidance on when to use this versus alternatives like 'ae_cameraMove' or 'ae_set3D', nor any stated prerequisites or exclusions.

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