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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description need only add context. It does add useful scoping detail: animations are categorized as in/out and apply to video, image and text clips, while transitions apply only between touching clips. It says nothing about return shape (names vs. identifiers) or whether the catalog is project- or effect-dependent.

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?

One short sentence with no filler and the two result categories front-loaded. The only structural weakness is the fragment style: it leads with a noun phrase rather than a verb, so the reader must supply 'List' from the tool name.

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?

This is a simple read-only enumeration tool with one optional parameter and no output schema, so little explanation is demanded. Still, an agent cannot tell from the description what it receives back (labels, IDs, or full type descriptors) or whether the result set depends on projectId, which matters for calling it correctly before set_animation or set_transition.

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?

There is a single optional parameter, projectId, and schema description coverage is 100%, so the schema already explains that it defaults to the open project. The description adds no meaning beyond that. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 is a noun phrase naming the two catalogs it returns: in/out animation types (scoped to video, image and text clips) and transition types (between touching clips). The action verb 'list' only comes from the tool name, and the description never states that it returns the set of valid values, so the purpose is inferable but not explicit. It does distinguish itself from neighboring list_* tools by resource, which keeps it above a tautology.

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 only implied: an agent can infer this is a discovery call to look up valid animation/transition types, and that transitions only apply between touching clips. It never names the natural follow-up actions, set_animation and set_transition, nor states that this tool is read-only discovery before those mutations. No when-not guidance is given, though for a small catalog lister that is a modest gap.

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