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

The annotations already declare readOnlyHint=false, so the description does not need to re-state that it mutates. It does add value by disclosing that it returns the new layer's index, which is behavioral information. However, it does not mention potential side effects such as changing the active selection or requiring a specific project state. Given the annotations cover the core mutation trait, this is adequate but not rich.

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?

The description is two sentences and front-loads the core action ('Add a layer to a composition') followed by the allowed types and return value. It avoids repeating schema details and contains no filler, making every word purposeful.

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?

Given the tool's complexity (20 parameters) and a rich schema that documents all parameters, the description sufficiently conveys the tool's purpose and return value. It does not enumerate every edge case, but the schema covers those. The explicit return-value mention mitigates the lack of an output schema, making the definition complete enough for an agent to call it 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 100%, with each of the 20 parameters having a description that includes defaults, constraints, and examples (e.g., font format, default sizes). The tool description does not add parameter-specific guidance beyond the schema, so it receives the baseline score of 3.

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 the verb 'Add' and the resource 'a layer to a composition' and enumerates the supported layer types (text, solid, shape, null, adjustment, camera, light, footage/comp). It also mentions the return value, the new layer's index, which distinguishes it from sibling tools like ae_set_layer (modifies existing layers) and ae_create_comp (creates compositions).

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?

The description clearly frames the tool as adding new layers, and the context of the sibling tools (especially ae_set_layer for modifications) implies the use case. However, it does not explicitly state when NOT to use this tool or mention alternatives like ae_import for footage-only scenarios. The context is clear but exclusions are not stated.

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

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

Annotations already declare readOnlyHint=false, and the description confirms this is a mutating operation by saying it adds an effect. It adds useful context about setting parameters in the same call and accepting display names or matchNames, but it does not disclose side effects or failure 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?

Two front-loaded sentences with no filler. The first states the operation and optional behavior; the second gives identifier formats and examples.

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 mutating tool with five parameters and a nested object, the description plus schema provides enough context to select the tool and invoke it correctly: effect name, layer, comp, and parameters are all covered. Missing return/error behavior is a minor gap but not critical for selection.

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 100%, and the schema already documents each parameter, provides an example for the parameters object, and explains color format and where to find exact parameter names. The tool description repeats only the display-name/matchName distinction with examples, adding marginal value.

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 action ('Add an effect to a layer') and a clear resource, plus optional parameter setting. This distinguishes it from siblings like ae_remove_effect and ae_set_property, and concrete identifier examples reinforce the purpose.

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?

The description implies the primary use case: adding an effect and optionally setting parameters in one call. However, it does not explicitly name alternatives or state when not to use this tool, though the schema does point to ae_list_effect_params for parameter-name lookup.

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

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

Annotations already declare readOnlyHint=true, so no side-effect disclosure is needed. The description adds useful scope detail about what the read includes, but it does not describe output format, pagination, size limits, or any other behavioral trait beyond the annotation.

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?

Two sentences with no filler. The operation and scope are front-loaded, and the usage context ('before editing anything') is placed at the end without disrupting the core message.

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 read-only inspection tool with two optional, fully documented parameters and no output schema, the description provides enough context to call it correctly. It lacks return-structure details, but the schema and annotations cover the remaining essentials.

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 100%, with both parameters (comp and detail) fully documented, including defaults and enum values. The description reiterates the overall purpose but adds no parameter-specific meaning beyond what the schema already provides.

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 a concrete operation ('Read a composition's settings and its layer stack') and enumerates its scope (transform, effects, keyframed/expression-driven properties). This clearly distinguishes it from edit/set/apply siblings like ae_set_comp_settings or ae_set_layer.

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?

The description explicitly states this is 'the tool to call before editing anything', giving a clear situational trigger. However, it does not mention alternatives or exclusions, so it stops short of a full when-not guide.

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

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

Annotations only indicate that the tool is not read-only and not open-world. The description adds useful behavioral context: creating also opens the comp in the timeline, and backgroundColor is purely a preview convenience and will not appear in rendered output. No contradiction with annotations.

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?

Two sentences with no filler: the first states the primary action and side effect, the second delivers the most important non-obvious caveat. Every sentence earns its place.

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 all parameters documented in the schema and the key rendering caveat explained, the description is sufficient for a competent agent to invoke the tool correctly. It does not state the return value, and there is no output schema, but that is a minor gap for a creation tool.

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. The description adds meaningful semantic value beyond the schema for backgroundColor—that it is preview-only and needs a solid layer to appear in renders—which the schema's format-focused description does not convey.

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 ('create') and resource ('new composition') and adds a concrete side effect—opening it in the timeline. This clearly distinguishes the tool from sibling tools that list, inspect, or modify existing comps.

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?

The word 'new' implies this tool should be used for creating comps rather than modifying existing ones, but the description offers no explicit when-to-use guidance or named alternatives. The agent must infer the appropriate context from the verb alone.

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

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

Annotations already declare the mutation profile (readOnlyHint=false), so the description only needs to add context. It adds the exact-match constraint, which is useful, but does not describe failure behavior or side effects beyond 'execute'.

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?

Two tight sentences deliver the core action, purpose, examples, and a critical constraint. No filler; the most important usage caveat is front-loaded near the purpose.

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 single-parameter tool with no output schema, the description covers purpose, valid examples, and matching constraint. It could mention how to discover valid menu names or what happens on an unmatched command, but the low complexity makes it reasonably complete.

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. The description adds value by insisting 'Names must match the menu exactly' and providing valid examples, which helps an agent format the single 'command' parameter correctly.

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 action and resource: 'Execute an After Effects menu command by name,' with concrete examples ('Auto-Orient', 'Fit to Comp', 'Purge All Memory'). It also distinguishes itself from scripting-API tools by noting it is for things with no scripting API, setting it apart from siblings like ae_run_script.

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?

Provides clear context: use when there is no scripting API, with illustrative examples. It does not explicitly name alternatives or say when not to use it, but the context strongly implies the boundary against scripting-based tools.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. The description adds that it reads current value, keyframes, expression, and children, which goes beyond the annotations and explains the multi-part return behavior. It does not contradict annotations.

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?

Two sentences, front-loaded with the primary function and return content. The second sentence adds a practical hint about discovering parameter names, earning its place.

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 read tool with annotations covering safety and no output schema, the description is mostly complete. It explains the return includes value, keyframes, expression, and children. It could mention that 'comp' and 'layer' are optional and default to active/selection, but the schema already covers that; nothing critical is missing for calling it 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 coverage is 100%, so the schema already documents all four parameters. The description adds value by showing that 'property' can be an array for exact addressing and notes that children listing reveals parameter names, but it doesn't go deep into time/format semantics. Given full schema coverage, a 4 is appropriate.

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 ('Read') and resource ('a property'), and explicitly mentions what is returned: current value, keyframes, expressions, and children. This distinguishes it from sibling tools like ae_set_property, ae_set_keyframes, and ae_set_expression.

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?

The description says it also lists property children, which is how you discover exact parameter names, giving a clear use case for exploration. It doesn't explicitly say when not to use it versus alternatives, but as a read tool it is clearly distinct from the set/remove/apply siblings.

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

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

The description discloses supported media types and the fact that new item IDs are returned, which goes beyond the sparse annotations. It does not, however, mention duplicate-handling behavior, failure cases, or what happens with invalid paths, which would be useful for a mutating import tool.

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?

Two concise sentences with no filler. The main action is front-loaded, and the additional details about media types and return value each add value.

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 low-complexity three-import with full schema coverage spells, the description plus schema covers required inputs, supported file types, and the return contract. Since there is no output schema, the explicit mention of returned item IDs is valuable.

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%, and the schema already documents all three parameters clearly. The description adds light context by mentioning image sequences, but it does not meaningfully extend the parameter semantics beyond the schema.

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 action ('Import files into the project'), names the supported media types, and explicitly says it returns item IDs to use with ae_add_layer. This differentiates it clearly from sibling tools like ae_add_layer and ae_run_script.

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?

Gives clear workflow context: use it to bring media into the project before adding layers with ae_add_layer. It does not explicitly name alternatives or say when not to use it, but the intended use case is unambiguous.

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

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

The description openly indicates mutation: duplicating, deleting, reordering, precomposing, and splitting are all structural changes, consistent with readOnlyHint=false. It adds context like 'into a new comp' and 'at the current time,' but it does not disclose consequences such as whether precompose modifies the original stack or what happens to references.

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 efficiently lists all five operations with no filler or repetition. Every part of the description adds information, and the operation list is immediately visible.

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 complex dispatcher with 7 parameters and 5 operations, yet the description provides only a one-line summary. The schema compensates by documenting parameter-specific constraints, but the description does not tie together how the op value selects which parameters apply, nor does it explain split's reliance on current time.

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 high at 86%, so the baseline is 3; the schema already explains each parameter's role. The description adds minimal additional parameter semantics beyond mapping operations to their concepts, so it does not push above the baseline.

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 a specific resource ('layers') and lists concrete structural operations: duplicate, delete, move, precompose, and split. This clearly distinguishes it from sibling tools that add layers, set properties, or manipulate effects, even without naming them.

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?

The phrase 'Structural operations on layers' implies the intended scope, and the operation list helps an agent decide what this tool can do. However, it does not explicitly state when to prefer this tool over siblings like ae_add_layer or ae_set_layer, nor does it give any when-not-to-use guidance.

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

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

The annotations already declare readOnlyHint=true, so the description's read-only nature is redundant. The description adds the detail that it returns size, duration, and frame rate for each composition, which is a light behavioral trait. It does not disclose edge cases like empty projects, sorting order, or performance implications for many comps, but given the read-only annotation covering safety, the additional value is modest.

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?

The description is a single sentence with no filler. It front-loads the core action ('List every composition in the project') and then lists the key attributes. Every word contributes value, making it an exemplar of concise, structured descriptions.

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 parameterless listing tool with read-only annotations, the description is nearly complete. The only minor gap is that it does not explicitly state the return format (e.g., array of objects), but since there is no output schema, an agent must infer from typical tool behavior. The scope is clear, and the tool's simplicity means the description covers the essential context.

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?

The tool has zero parameters回报, so the description does not need to explain parameter meaning. The schema coverage is 100% (trivially, as there are no parameters), and the description clearly states what is returned (size, duration, frame rate). This is sufficient for an agent to invoke the tool without further parameter guidance.

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 ('list') and resource ('every composition in the project'), and clearly enumerates the returned attributes (size, duration, frame rate). It distinguishes itself from sibling tools like ae_comp_info by implying a comprehensive listing, whereas ae_comp_info likely targets a single composition. The scope is unambiguous.

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?

The description implies usage for retrieving an overview of all compositions, but does not explicitly state when to prefer it over alternatives like ae_comp_info or ae_project_info. It does not provide exclusion criteria or context such as 'use this to get a high-level view before drilling into individual comps'. However, the verb 'list every' clearly indicates a bulk enumeration, which distinguishes it from singular counterparts.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description does not contradict that. It adds behavioral context by clarifying the effect must already be applied to the layer and by describing the returned payload (all parameters, current values, types), which is valuable absent an output schema.

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?

Two sentences, front-loaded with the action and result, and the second sentence earns its place by connecting the tool to its downstream callers. No filler.

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 3-parameter read-only tool with complete schema coverage, the description provides the key return contract (values and types) even though no output schema exists. It could have mentioned omitted comp/layer fallbacks, but those are already documented in the schema, so nothing essential is missing.

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 100%, so the schema already documents comp, layer, and effect semantics. The description's phrase 'already on a layer' reinforces that effect targets an existing instance rather than a preset, but it does not add meaningful syntax or default-behavior details beyond the schema.

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 ('List'), a precise resource ('every parameter of an effect already on a layer'), and the data returned (current values and types). It also frames the purpose against downstream tools (ae_apply_effect, ae_set_property), which distinguishes it from generic inspection tools in the sibling set.

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 provides explicit guidance that this is the discovery step before applying or setting properties ('This is how you discover the exact names...'), which tells an agent when it is useful. It does not name negative cases or alternative tools such as ae_get_property, so it falls just short of full when/when-not coverage.

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

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

Annotations already mark it read-only, so the safety profile is known. The description adds valuable behavioral context beyond the schema: a font that isn't in this list silently does nothing in dependent tools, and the returned names are the exact values expected by the setter tools. This over-delivers relative to the annotation baseline.

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?

Two tightly written sentences, with the main purpose in the first and the practical caveat in the second. No filler, no repetition of schema content; every clause earns its place.

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 an optional-parameter read-only listing tool, this is complete: it states what is listed, the exact naming detail, the intended consumers, and a critical failure mode. No missing information prevents an agent from calling it correctly, and no output schema is required for a simple listing.

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 100%, with limit and query already documented (default 80, case-insensitive substring), so the description doesn't need to add parameter detail. It adds only contextual value about how the returned names are consumed, not new meaning for the parameters themselves. Baseline 3 is appropriate.

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 a specific verb ('List'), a concrete resource (fonts installed for After Effects), and the key output detail (PostScript names). This distinguishes it from every sibling tool; no other sibling claims font listing.

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 explicitly tells the agent when to use this tool: before ae_add_layer and ae_set_text, because those tools expect PostScript names. It lacks an explicit 'when not to use' or alternative-tool exclusion, but there is no sibling font-listing tool, so this is clear context.

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

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

Annotations only indicate this is not read-only, so the description carries the behavioral burden. It discloses a key safety trait: the tool fails rather than discarding unsaved work, and explains how to override that behavior deliberately. This goes beyond the schema and gives useful operational context.

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?

Two short paragraphs, no filler. The first sentence states the core function, and the second provides the critical safety/usage constraint. Every sentence earns its place.

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 tool with two parameters, no required params, and no output schema, the description fully covers what an agent needs: how to open, how to create, what failure mode to expect, and how to handle unsaved changes. It mentions the relevant sibling tool for saving, completing the workflow context.

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 100%, with both path and discardChanges already well documented. The description adds some context by mentioning ae_save_project and discardChanges, but it mostly restates behavior already present in the schema, so baseline 3 is appropriate.

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?

Description states a specific verb and resource: 'Open an .aep file, or start a new empty project.' It clearly distinguishes itself from siblings like ae_create_comp (new composition) and ae_save_project (save), so an agent can tell what this tool does.

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?

Provides explicit guidance: if the current project has unsaved changes, save it first with ae_save_project or pass discardChanges to intentionally discard. It also clarifies that omitting path creates a new empty project. This is direct when-to-use and alternative routing.

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

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

Annotations already declare readOnlyHint=true, so the read-only behavior is established. The description adds valuable context beyond annotations by stating the output includes 'ids you can pass to other tools', which is useful for planning multi-tool workflows. No contradiction with the read-only hint.

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 sentence that front-loads the purpose, enlists the eligible item types, and ends with a note on the output's utility. No wasted words, but it could be slightly tighter by removing the duplicate 'everything' and 'all' in the schema.

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 simple read-only list tool with two optional parameters and no output schema, the description covers the foundational information well: scope, content, and value proposition (IDs for other tools). It leaves a minor ambiguity about whether solids are a separate kind in the schema (the enum only lists comp, footage, folder, and all), but that is a small gap for a tool of this simplicity.

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% – both 'kind' and 'search' are fully described in the schema. The description adds no explicit parameter guidance beyond mentioning the item types included in the default 'everything', but that's already clear from the schema's enum and default. No added value beyond the schema.

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 clear action (List), a precise resource (Project panel), enumerates the item types (comps, footage, solids, folders), and mentions IDs are returned for use in other tools. This distinguishes it from siblings like ae_list_comps without needing to open either schema.

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?

The description implies this is the broad enumeration tool ('List everything in the Project panel') and notes IDs are for other tools, but it does not explicitly contrast with ae_list_comps or state when to choose one over the other. The guidance suggests usage for general listing, but exclusions and alternatives remain implicit.

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

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

The description clarifies the two modes of operation—removing versus disabling—which goes beyond the bare annotations. However, it does not state whether deletion is reversible, what happens if the effect does not exist, or how the tool behaves with invalid targets. With annotations only indicating mutable behavior, this is acceptable but not rich.

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?

The description is a single efficient sentence that conveys the primary action and its alternative. It is front-loaded and contains no filler, though 'just switch it off' is slightly informal and could be clearer.

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?

Even with no output schema, the mutation-only nature of the tool is straightforward, and the schema fills in the selection/omission rules for comp and layer. The description adds enough context for a basic invocation, but could improve by mentioning behavior around selections and invalid effect names.

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 100%, so the schema already documents all parameters. The description's pointer to 'switch it off' maps to disableOnly but does not add meaning beyond the parameter documentation. Baseline 3 is appropriate.

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 explicitly states a specific verb ('Delete') and resource ('an effect from a layer'), and names the alternate behavior ('switch it off'). This distinguishes it from siblings like ae_apply_effect, ae_search_effects, and ae_remove_keyframes without needing to inspect their schemas.

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?

The description provides no guidance on when to choose this tool over alternatives, nor does it mention any exclusions or preconditions. An agent cannot tell from the description whether ae_remove_keyframes would be more appropriate for a given task, or when disableOnly should be preferred over deletion.

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

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

Annotations already signal a mutating operation (readOnlyHint=false), so the description's 'Delete' is consistent and adds no contradiction. It does add the behavioral scope that all keyframes are removed when no range is supplied, and only those in a range when from/to are provided. It does not disclose irreversibility or fallback behavior, but the annotation coverage lowers the burden.

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 14-word sentence states the action, resource, and scope with no filler. The most important qualifier ('all of them, or those inside a time range') is front-loaded immediately after the verb phrase.

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?

The tool has five parameters, but all are documented in the schema and only one is required; the description covers the core deletion semantics. No output schema exists, but for a delete operation no return format needs explanation. Missing usage guidance and alternatives slightly reduce completeness, but the combination of schema and description is otherwise adequate.

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 100%, so every parameter (property, layer, comp, from, to) is already documented. The description only references 'property' and 'time range' without adding format, units, or default semantics beyond the schema. A baseline of 3 is appropriate because the schema does the heavy lifting.

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 uses a specific verb ('Delete') and resource ('keyframes from a property'), and clearly scopes the action ('all of them, or those inside a time range'). This distinguishes it from sibling tools like ae_set_keyframes, which sets keyframes, and ae_remove_effect, which removes effects.

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?

No explicit guidance is given on when to use this tool versus alternatives such as ae_set_keyframes or ae_get_property. The only usage context is the all-or-range scope, which describes the tool's behavior rather than selection criteria. This is closer to no guidance than to a clear directive.

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

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

The annotations only mark readOnlyHint=false and openWorldHint=false, so the description adds important behavioral context: 'After Effects is blocked while this runs.' This is a material behavioral trait that an agent needs to know before invoking, and it is not captured by the annotations. It could mention results/failure behavior, but the overwrite modal behavior and timeout are already in the schema.

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?

The description is compact: one action sentence, one warning, and one routing alternative. It is front-loaded and every sentence earns its place without filler or repetition.

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 9-parameter mutation tool with no output schema, the description gives the essential behavioral warning, the action, and the alternative to use instead. All parameters are documented in the schema, so nothing needed to invoke correctly is missing; a small gap is that the return/result behavior is not described, but that is secondary for a render tool.

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 100%, so the baseline is 3 and the description does not need to repeat parameter details. The 'keep the range short' hint relates to start/end but does not add new parameter-level meaning beyond what the schema already documents.

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 action with a verb and resource: 'Add a composition to the render queue and render it.' It also distinguishes itself from the sibling ae_save_frame by noting that tool is for 'quick visual checks instead,' so an agent can tell which operation to choose.

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 when-to-use guidance by warning that After Effects is blocked and advising to keep the range short unless truly intended, and it names an alternative, ae_save_frame, for quick visual checks. This is clear selection guidance beyond the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds environment-specific scope ('in this install') and positions the output as input to ae_render, but it does not describe output structure or ordering. Consistent with the calibration precedent for read-only list tools whose annotations carry the safety burden, a 3 is appropriate.

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 sentence that front-loads the action and resource, then adds scope and purpose. Every clause carries information — action, object, environment scope, and intended downstream use — with no filler.

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 0-parameter, read-only listing tool, the description covers what it lists, the scope, and the downstream use. The absence of an output schema leaves the exact return structure unspecified, but the description conveys that template names are returned, which is sufficient for an agent to call the tool and use its output.

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?

The tool has zero parameters with trivially 100% schema coverage, so the baseline is 4. The description adds value beyond the empty schema by explaining what the returned data will be used for (valid names for ae_render), helping the agent interpret the results correctly.

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 uses a specific verb ('List') with a clearly identified resource ('render settings and output module templates available in this install'), and explains the downstream purpose ('so you can pass valid names to ae_render'). This differentiates it from sibling list tools like ae_list_comps, ae_list_fonts, and ae_list_effect_params, which target different resource types.

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?

The description states when the tool is useful — before calling ae_render, to obtain valid template names. It gives clear contextual guidance for an agent deciding between this and sibling listing tools, though it does not explicitly name alternatives or exclusion conditions.

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

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

The description discloses a great deal beyond the sparse annotations: the script runs as a function with return-value serialisation, the full AE API plus AEMCP helpers are available, args arrive as ARGS, and ES3 restrictions apply. This materially changes how an agent writes the script.

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?

The description is dense but every sentence carries operational information: purpose, execution model, helpers, args guidance, and ES3 constraints. It is well-structured and front-loaded with the core purpose.

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 high-complexity arbitrary-code tool with no output schema, the description covers purpose, execution semantics, helper API, argument passing, and language limitations. It doesn't explicitly state error behaviour or what happens when no return is used, but it is otherwise complete enough for an agent to invoke it 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 coverage is 100%, so the baseline is 3. The description adds valuable semantics beyond the schema: the script body is a function, return values are JSON-serialisable, args arrive as ARGS, and args are preferred over pasting values. UndoLabel and timeoutSeconds are left to the schema, but that is acceptable.

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?

Description opens with 'Run arbitrary ExtendScript inside After Effects' — a specific verb and resource. It then positions itself as 'the escape hatch for anything the other tools don't cover', clearly distinguishing it from the large sibling set.

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 explicitly says to use this when other tools don't cover the need, and gives examples (masks, shape operators, text animators, puppet pins). It does not name specific alternatives or state when not to use it, but the guidance is clear enough for an agent to route to it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the PNG has a transparent background because comp background color is a preview setting and never renders, and it advises adding a solid layer for an opaque backdrop. This is exactly the kind of non-obvious behavior an agent needs to know. It doesn't mention performance or file size implications, but the transparency disclosure is significant.

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?

The description is two short paragraphs, front-loaded with the core action and purpose. Every sentence earns its place: the first sentence states what it does, the second explains when to use it, and the third paragraph discloses a critical behavioral gotcha. No fluff or repetition.

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 read-only preview tool with 100% schema coverage and no output schema, the description is nearly complete. It covers the core action, the use case, and the transparent-background gotcha. It could mention that the returned image is what the agent will see (i.e., the response contains the image), but the returnImage parameter and the phrase 'return it as an image' already imply that. The only minor gap is not explaining what happens if the comp is missing or the time is invalid, but that's not essential for a read-only tool.

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 100%, so the schema already documents all 5 parameters. The description adds context about the default behavior (returning an image) and the transparent background, but doesn't add much per-parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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 ('Render a single frame... to PNG and return it as an image') and resource ('a composition'), and clearly distinguishes it from the sibling ae_render by emphasizing single-frame preview and visual checking. It also explains the purpose ('so you can see what the comp actually looks like'), which helps an agent understand when to use it.

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?

The description explicitly says to use this tool to check work after making changes and warns not to assume an edit landed as intended. It also provides a clear exclusion/alternative context by contrasting with rendering a full composition (sibling ae_render), and gives practical guidance about transparent backgrounds. This is strong usage guidance.

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

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

Annotations indicate this is a write operation (readOnlyHint=false), and the description confirms persistence behavior. It adds some context by distinguishing in-place overwrite from Save As, but it does not disclose details such as whether unsaved changes are silently discarded or how overwrite confirmation is handled.

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?

The description is one efficient sentence that front-loads the core action and then adds the only optional nuance. Every word earns its place.

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 one-parameter save operation with a complete schema, the description is largely sufficient. It would benefit from explicitly naming ae_save_frame as the alternative for frame output, but the tool is simple enough that this is a minor 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?

The schema already documents the single 'path' parameter at 100% coverage, including its type and meaning. The description adds only slight semantic value by explaining 'Save As' and the in-place behavior, which is enough to meet the baseline but not exceed it.

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 clear, specific verb ('Save') and resource ('current project'), and immediately distinguishes the two modes: save in place versus Save As to a new path. This is unambiguous and separates it from siblings like ae_save_frame.

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?

The description clarifies when to omit the path (save in place) and when to provide one (Save As), but it never explicitly says when to use this tool versus alternatives such as ae_save_frame or ae_export. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it returns exact matchNames, which is useful, but it doesn't disclose details like case-insensitivity of the query or default limit behavior. With annotations covering the safety profile, a 3 is appropriate.

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?

Two sentences with zero waste. The purpose is front-loaded, and the usage guidance is concise. Every sentence earns its place.

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 read-only search tool with 100% schema coverage and no output schema, the description is nearly complete. It could mention that the output is a list of matchNames, but the description already says 'get their exact matchNames.' The only minor gap is not describing the output format, but that's not required given the tool's simplicity.

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 100%, so the schema already documents both parameters (limit and query). The description adds the context that the query is a case-insensitive substring and that results are matchNames, but it doesn't add significant meaning beyond the schema. Baseline 3 is correct.

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 clearly states the tool's purpose: searching installed After Effects effects and retrieving their exact matchNames. It also explicitly names the sibling tool ae_apply_effect, distinguishing this search tool from the application tool.

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?

The description explicitly says to use this tool before ae_apply_effect when unsure an effect exists or how it's spelled. This provides clear when-to-use guidance and names the alternative, leaving no ambiguity.

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

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

Beyond readOnlyHint=false, the description reveals that selection is persistent state consumed by other tools and that it is a mutating operation on that state. No contradiction with annotations. It does not discuss whether selection is replaced vs merged, but 'Change' plus schema's deselect behavior keeps this adequate.

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?

Two sentences with no filler. The action word is front-loaded, and the second sentence earns its place by explaining cross-tool consequence.

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 tool with two optional params, full schema descriptions, and no output schema, the description covers the important operational concept (selection as fallback). A fully explicit statement that selection replaces any prior selection, and layer identifier formats, would push it to 5, but these are inferable.

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 parameters carry their own meaning (comp and layers/deselect). The description does not add parameter-level detail; it only reinforces the high-level selection concept. Baseline 3 is appropriate.

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 first sentence names a concrete action and object: 'Change the timeline selection.' The next sentence positions it in the workflow ('Other tools fall back to the selection when you omit `layer`'), which distinguishes it from the sibling layer/property tools and explains why this tool exists.

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 usage context: select once so later commands that omit layer apply to the chosen layers. It does not enumerate which siblings are affected or state when to bypass this tool and pass layer directly, so it stops short of explicit when-not/exclusion guidance.

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

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

The annotations already mark this as a write operation (readOnlyHint=false), and the description matches by enumerating the settings it mutates; there is no contradiction. However, it adds no further behavioral context such as reversibility, effects on existing layers, or active-composition fallback 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?

The description is a single front-loaded sentence with no filler. Every phrase maps to a parameter or capability, and it avoids repeating schema details.

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?

The description captures most configurable settings and, combined with the fairly descriptive schema, lets an agent invoke the tool correctly. It omits resolutionFactor and any return or error behavior, but for a setter tool with schema-provided parameter details, these are minor gaps.

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?

The schema covers 60% of parameters and already documents comp, duration, work areas, backgroundColor, and resolutionFactor. The description adds meaning to otherwise undocumented parameters: 'Rename' clarifies name, 'resize' clarifies width/height, and 'frame rate' clarifies frameRate. It does not mention resolutionFactor, but it compensates for most schema gaps.

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 uses specific verbs ('Rename or resize', 'change') and names the exact composition settings it affects: duration, frame rate, work area, and background. This clearly differentiates it from sibling tools like ae_create_comp and ae_comp_info even without naming them.

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?

The description implies use for mutating an existing composition's settings, but it does not explicitly state when to choose this tool over alternatives such as ae_create_comp or ae_comp_info. There are no exclusions, prerequisites, or alternative-routing hints, so usage guidance is only inferred from the word 'change'.

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

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

Annotations declare readOnlyHint=false, so the agent knows this is a mutating operation. The description adds the key behavioral detail that omitting or passing an empty string clears the expression, which is critical for correct invocation. However, it does not disclose potential side effects (e.g., whether setting an expression overrides an existing keyframe value, or whether the property must be animatable). With annotations covering the mutation safety profile, a 3 is appropriate.

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?

Two sentences with zero waste. The primary action is front-loaded, and the second sentence adds essential context about the expression language. Every word earns its place.

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 mutating tool with no output schema, the description covers the core behavior (set or clear) and the expression language. The schema covers all parameters. The only missing context is when to prefer this over ae_set_property, but the sibling list and tool name largely disambiguate that. Overall, an agent has enough to call this 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 100%, so the schema already documents all four parameters. The description adds the crucial semantic that 'expression' can be omitted or empty to clear, which is not fully explicit in the schema. However, it does not add detail about the property path formats beyond what the schema already provides. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Attach' or 'clear') and a specific resource ('an expression to a property'), and it distinguishes the two modes of operation. It also clarifies the expression language (After Effects' JavaScript expression language), which helps an agent understand what the 'expression' parameter should contain. This clearly differentiates it from sibling tools like ae_set_property or ae_get_property.

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?

The description implies the primary use case: attaching or clearing an expression on a property. It does not explicitly state when to use this tool versus alternatives like ae_set_property, but the sibling list and the tool name make the distinction fairly clear. The description could be improved by explicitly saying 'Use this instead of ae_set_property when you need to set an expression rather than a static value,' but the current wording is adequate.

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

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

The description discloses two useful behavioral traits: existing keyframes at the same times are replaced, and easing defaults to smooth ease in and out. With only readOnlyHint=false and openWorldHint=false annotations, this context adds value beyond the structured fields and does not contradict them.

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?

Three sentences, front-loaded with the core action, followed by scope clarification and key behavior. Every sentence earns its place; there is no filler or repetition of schema details.

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?

Given the 9-parameter schema with 89% coverage, the description is adequately complete for correct invocation. The key behavioral details (replacement and easing default) are present, while remaining parameter semantics are well covered by the schema. It does not describe return values, but no output schema exists and the description isn't expected to.

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 high (89%), so the baseline is 3. The description adds value by explaining the default easing in human terms ('smooth ease in and out') and by listing property categories such as mask paths, shape properties, and text animators that go beyond the schema's examples. This meaningfully supplements the schema.

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: 'Set keyframes on any animatable property', followed by a concrete list of property categories. This clearly differentiates it from siblings like ae_set_property (static value) and ae_remove_keyframes (removing keys), even without naming them.

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?

The action is clear, and the broad 'any animatable property' implies when to use it, but there is no explicit guidance about alternatives or when not to use it. An agent would benefit from a pointer to ae_set_property for static values or ae_remove_keyframes for clearing keys, but the description leaves this inferred.

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

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

The description goes beyond the sparse annotations by disclosing that all values are set statically and that animation should be handled separately. This is a meaningful behavioral trait, though it stops short of explaining what happens if a property already has keyframes or whether changes are reversible.

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?

The description is one efficient sentence that front-loads the primary action and property scope, then adds the key static-versus-animated distinction. Every clause earns its place, and there is no redundant restatement of the name or title.

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 21 parameters and no output schema, the description gives the essential context: what is changed, that values are static, and the keyframes alternative. It could be more complete by noting behavior around existing keyframes or selecting layers when omitted, but the schema covers selection defaults and the description is sufficient for most invocation decisions.

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?

The input schema already documents many parameters with units and examples, and the description adds a useful category-level summary such as 'timing' and 'switches'. However, with 21 parameters and only 62% schema coverage, the description does not fully compensate for the undocumented parameters like anchorPoint, adjustmentLayer, or motionBlur, though many are inferable from their names.

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 clear action ('Change'), a specific resource ('a layer'), and enumerates the affected property categories: name, transform, timing, parenting, blend mode, and switches. It also distinguishes itself from ae_set_keyframes by clarifying that values set here are static, which is exactly the kind of differentiation an agent needs.

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?

The description explicitly instructs the agent to use ae_set_keyframes when animation is desired instead of static values. This is a clear when-to-use signal for the most important alternative, though it does not address possible overlap with other sibling tools like ae_set_property or ae_set_text.

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

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

Annotations already carry readOnlyHint: false and openWorldHint: false, so the mutation intent is known. The description adds that the value is static (vs animated) and that it can apply to 'anything ae_comp_info shows'. However, it does not disclose side effects like overwriting existing keyframes, whether the property must already exist, or error conditions—but since annotations already cover basic non-read-only behavior, a 3 is fair.

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?

Two sentences, front-loaded with the purpose and the distinguishing instruction ('use ae_set_keyframes to animate instead'). No filler or repeated schema facts. Every sentence earns its place.

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?

The description gives the main decision point (static vs keyframes), a pointer to ae_comp_info for discovering properties, and a clear example path. The only missing piece is what happens to existing keyframes or animation on the property when setting a static value—worth mentioning, but given the schema+annotations already carry the required and mutating behavior, the description is quite complete for correct selection and usage.

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 listed at 100%, so the schema already provides all param descriptions. The description adds meaning by explaining 'static value', 'by path', and giving examples that overlap the schema but are not redundant. It gives gentle extra context (effect parameters, mask feather, shape sizes) beyond the raw schema, which is helpful but does not heavily compensate because the schema already covers the structure.

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 ('set') applied to a concrete resource ('any property by path') with explicit examples (effect parameters, mask feather, shape sizes). It also differentiates itself from the sibling ae_set_keyframes by saying 'use ae_set_keyframes to animate instead', so an agent can distinguish purpose without opening the schema.

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 explicitly tells when to use this tool (setting a static value on a property) and when not to (use ae_set_keyframes to animate instead). It additionally grounds usage by referencing ae_comp_info for discovering property paths, which is a practical routing hint for the agent.

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

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

The description's 'change' matches readOnlyHint=false, so there is no annotation contradiction. But it adds little behavioral context beyond that: it doesn't say what happens if the layer or comp is omitted, whether unspecified style properties are preserved, how invalid fonts or colors are handled, or what the tool returns. With 12 optional parameters, the description leaves the mutation behavior largely undisclosed.

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?

The description is a single tight sentence with no filler and front-loads the main action. It is concise without being bloated, but it sacrifices useful operational detail that other dimensions need; the brevity itself is not a flaw, but the sentence is more of a restatement of the title than a substantive expansion.

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 tool with 12 parameters, zero required parameters, no output schema, and only minimal annotations, this description is too thin. It does not mention the optional-layer/comp fallback behavior, the absence of required arguments, parameter categories, or likely failure modes, leaving an agent under-equipped to invoke it correctly on a complex text-layer mutation task.

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 58%, and the description does not compensate for the undocumented parameters. 'String and character styling' is a useful umbrella for text, font, color, leading, tracking, etc., but it does not clarify the ambiguous parameters (tracking, allCaps, strokeWidth, justification, fontSize) beyond what their names already imply.

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 uses a specific action ('change') and a clear resource ('the string and character styling on a text layer'), so an agent can tell it targets text content and typography. It does not explicitly contrast itself with sibling tools like ae_set_layer or ae_set_property, but the scoping to text layers is enough to avoid gross confusion.

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?

The phrase 'on a text layer' implies the intended use: modify a text layer's content and character-level style. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as ae_set_property or ae_set_layer, leaving the decision partly to inference.

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

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

Annotations already indicate readOnlyHint=false, so the description need not restate that it is not read-only. The description adds value by disclosing the side effect on ae_save_frame, clarifying that this changes the playhead position which influences subsequent saves. No contradictions with annotations are present, and the effect on save_frame is a meaningful behavioral trait.

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?

The description is just two sentences, each earning its place: the first states the core action and target, the second highlights the important downstream effect. There is no redundancy, filler, or unnecessary detail, making it an ideal length.

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 simple two-parameter tool with no output schema and full parameter documentation, the description gives the essential context—including the tie to ae_save_frame. It doesn't mention result values, but the tool's purpose is pure side-effect; the omission is acceptable. The description is complete enough for an agent to invoke 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 coverage is 100%, so the comp and time parameters are already well-documented. The description doesn't go beyond the schema for parameter meaning—it just restates the operation. According to the rubric, with high schema coverage the baseline is 3, and there is no additional semantic nuance provided here.

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 'Set the current time in a composition' clearly specifies the verb and resource, while 'Affects what ae_save_frame captures' ties it to a concrete downstream effect. This distinguishes it from siblings like ae_save_frame, ae_render, and ae_set_comp_settings without ambiguity.

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?

The phrase 'Affects what ae_save_frame captures' implies the primary use case: set the playhead before calling ae_save_frame to control the captured frame. It gives clear context for when to use the tool, though it does not explicitly state when not to use it (e.g., when manipulating layers instead). This lack of exclusion is minor for such a specific operation.

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

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

The description discloses an optional launch side effect ('Start After Effects if it isn't running'), which contradicts the annotation readOnlyHint=true because launching a process is not read-only. Even though the description is transparent about the behavior, it directly conflicts with the declared read-only annotation.

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?

The description is two sentences with no filler. It front-loads the core check/report action, lists the key outputs, explains relevance to other tools, and gives a clear starting-point instruction.

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 does a good job summarizing the reported values and the launch side effect. It could be slightly more explicit about the exact return shape, but for a status/diagnostic tool the essentials are present.

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 only one optional parameter, launch, and the schema already describes it fully, including the ~30s responsiveness caveat. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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 uses a specific verb ('Check whether After Effects is running and report') and names concrete outputs: version, open project, and script file-write permission. It clearly identifies the tool's scope and why it matters for ae_save_frame and rendering, so an agent can distinguish it from project-specific siblings.

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?

The description gives explicit context: use it to verify prerequisites for saving frames/rendering, and 'Start here if anything else fails.' It does not explicitly name alternatives or say when not to use it, but the diagnostic-first guidance is clear enough.

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

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

Annotations are minimal: readOnlyHint=false and openWorldHint=false, which indicate this is a mutating operation. The description doesn't add much beyond that, but it does mention the repeat behavior (stepping back multiple times). However, it doesn't disclose potential side effects like losing unsaved changes or limitations due to undo history limits, which would be useful given that the annotation already implies mutation.

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?

The description is short and to the point, with only two sentences. It is front-loaded with the main purpose. However, the second sentence 'Repeat to step further back' is somewhat redundant with the parameter, but it is informative and not wasteful.

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?

Given the tool's simplicity (one optional parameter, no output schema), the description is adequate to allow an agent to call it. However, it could be improved by mentioning that undo history is limited and that multiple steps can be specified via the parameter, making the second sentence unnecessary. But it probably is sufficient for basic usage.

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?

The schema description coverage is 100% for the single parameter 'steps', which explains its default value. The description adds a note about repeating to step further back, but that is redundant with the parameter's existence. The description doesn't add much new meaning beyond the schema.

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 the tool undoes the last operation in After Effects, which is a clear verb and resource. However, it doesn't explicitly distinguish it from the many sibling tools that also modify the project (e.g., ae_add_layer, ae_set_layer), though the 'undo' concept is somewhat self-explanatory. It could benefit from specifying that it undoes the previous editor action.

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?

The description does not provide when-to-use versus alternatives guidance. It only says 'Undo the last operation' and 'Repeat to step further back', which implies iterative use but there is no mention of when this tool should be preferred over other modification tools. Since there are many siblings that modify the project, this is a gap.

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