After Effects dialogs

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

The description itself is unusually forthcoming about side effects (a 'save changes?' question is cancelled, never answered for the user) and about platform/auth requirements (Accessibility permission on macOS for reading text and dismissing). However, that disclosure directly conflicts with the readOnlyHint=true annotation for the dismiss mode: closing a modal dialog changes application state, so an agent trusting the annotation may assume no side effects. Credit for the auth/permission detail is offset by this inconsistency.

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?

Information is front-loaded: verb+resource first, then dismiss semantics, then when-to-use, then platform caveat. Every clause earns its place, though the heavy parenthetical nesting makes it denser than ideal for scanning.

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 no output schema, the description still conveys that listing reports open dialogs and that dismiss requires an id sourced from a prior list or error. It stops short of describing the returned dialog fields (text, id shape) or what happens if the id is stale/an unknown dialog, which is the main remaining gap.

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 100%, so the baseline is 3 — both `id` and `action` are already documented in the schema, including the list/dismiss enum. The description adds genuine meaning beyond the schema by spelling out what `dismiss` does behaviourally (cancel-equivalent, Escape semantics) and where `id` comes from (a previous list or a DIALOG_OPEN error).

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 names both concrete operations — listing currently-shown modal dialogs and dismissing one via its cancel action — with a specific resource (After Effects modal dialogs) that no sibling tool touches. An agent can distinguish this from ae_do, ae_save_project, or any info tool at a glance.

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 explicit triggering conditions: use after a DIALOG_OPEN / TIMEOUT error, or proactively before a step known to pop a dialog. It also states what the dismiss mode semantically means (Escape behaviour) so the agent knows which of the two modes maps to its situation.

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