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

Annotations already establish that this is a non-read-only, non-destructive mutation. The description adds useful behavioral details beyond that, such as position with three values turning on 3D, anchor being applied before position, fit_to continuously fitting content, and timing semantics for in/out/source_in/stretch.

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 and front-loads the operation before moving through option semantics. However, the telegraphic single-paragraph style with semicolon-separated notes makes it denser and less scannable than it could be.

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 creation tool with nine layer kinds and a nested shape object, and the description covers many important option behaviors. It still leaves several fields and interactions unexplained, so it is adequate but not fully complete for the tool's complexity.

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 0%, so the description must carry parameter meaning, and it explains many non-obvious options: item_id, center, position/3D behavior, box_size and text_style, anchor ordering, shape, fit_to, fit, and timing fields. It still omits some parameters such as start, duration, name, size, color, light_type, and explicit three_d, so it is strong but incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Add a layer,' with comp_id and kind making the operation clear. It does not explicitly distinguish this from siblings such as duplicate_layer or add_shape, but the core purpose 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?

Usage is only implied by the tool name and option notes; there is no explicit guidance on when to use add_layer versus duplicate_layer or other creation tools. References like 'as set_text' and 'as add_shape' clarify option behavior, not tool selection.

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 readOnly=false, idempotent=false, destructive=false, openWorld=false, so the safety profile is covered. The description usefully adds that it returns the new property path (no output schema exists) and that it unblocks later set_property calls, but it does not say whether calling it on an existing property errors or duplicates, which matters given idempotentHint=false.

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?

Appropriately short in word count, but the second sentence is a dense run-on that chains group_path, match_name, appended paths, and three example match names into one clause. A bulleted structure for the setup steps would make it far more scannable; as-is it is readable but not well organized.

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 mutation tool with no output schema, the description covers the critical integration detail (return value feeds subsequent paths) and gives a concrete worked example, so an agent can act. Gaps remain around layer_id meaning and error/idempotency behavior, but nothing blocks a correct call.

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 0%, so the description carries the burden. It does explain match_name by example ('ADBE Text Animator') and shows group_path as an AE match-name path array, but layer_id is never described and the format of the returned/consumed path is conveyed only through one hard-coded text-animator example.

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?

Specific verb + resource ('Add a property or group') and it explicitly distinguishes itself from the sibling set_property by stating it reaches targets 'set_property cannot reach until it exists.' The only fuzziness is that 'property or group' covers two distinct resource kinds, but the After Effects framing makes the intent recoverable.

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 clause about set_property implies the use case (the target must already exist for set_property, so use this first), but usage is left to inference rather than stated. There is no explicit when-to-use/when-not phrasing, no mention of what happens if the property already exists, and no guidance on ordering relative to other setup 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 already declare this is a non-read-only, non-destructive mutation, so the safety burden is partly covered. The description adds useful context about the returned modifier path/property names and their relation to set_keyframes, but does not explain side effects, existing modifier behavior, or failure conditions.

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 front-loaded, compact, and every sentence contributes: operation scope, parameter mapping/default, and return usage. There is no redundant or filler text.

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 nested params and no output schema, the description covers the core operation and return values reasonably well. However, it leaves layer_id semantics and some behavioral details underspecified given the 0% schema description coverage.

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 0%, so the description must carry parameter meaning. It adds useful semantics for params, group_index default (1), and the modifier choices, but layer_id is never explained and nested params behavior remains only briefly described.

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: adding trim_paths, repeater, or round_corners to a shape group. It is clear enough to distinguish this from general property/effect tools, though it does not explicitly name a sibling alternative.

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 by saying the return values are for set_keyframes, but it does not explicitly say when to choose this tool versus add_property or other shape-related tools. Guidance is present but inferred 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 flag destructive/non-idempotent/write, and the description adds substantial context beyond them: keys derive from current values, exits accelerate, springs become expressions, timing defaults, and how push/drift land and run. It does not explicitly state which existing keyframes get overwritten, which is a notable gap for a destructive 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?

Front-loaded with the core action and dense with genuinely load-bearing detail (defaults, timing rules, stagger). However it reads as a single semicolon-chained block without structure, which hurts scanability even though little is wasted.

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 11-parameter, no-output-schema mutation tool, the description is largely complete on moves, styles, defaults, and timing. It leaves order/phase semantics unaddressed and never states the destructive consequence (overwriting existing layer animation), which an agent would benefit from knowing.

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?

With only 9% schema description coverage, the description carries the burden and delivers: per-move meanings, style options with defaults (snappy, smooth, spring, bounce, linear), direction default (up), amount default (4%), distance default (2% of comp height), time default (in point / out point - duration), and stagger semantics. This far exceeds what the bare schema provides; only order and phase are undocumented.

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 (animate) and resource (layers) plus the exact mechanism — keying a named move from current values. The enumeration of the eight moves (fade, pop, grow, slide, drop, spin, push, drift) makes it unmistakably distinct from siblings like set_keyframes, transition, or stagger.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied through the behavioral mechanics; there is no explicit 'use this when' or routing to alternatives such as stagger, transition, text_reveal, or copy_animation, which all overlap in the motion domain. An agent can infer intent but must guess when this tool is preferred over its 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?

Annotations already specify mutation, non-idempotency, and non-destructiveness. The description adds important behavioral detail beyond annotations: parameter assignment accepts name, match name, or 1-based index, and the effect is automatically removed if any parameter fails.

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, no filler, and the core effect-add behavior is front-loaded. The failure-cleanup sentence earns its place because it changes how an agent should treat parameter errors.

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 four parameters, nested params, and no output schema, the description should explain all invocation-critical parameters. It omits layer_id and name entirely and gives no format for params values, so an agent cannot fully determine how to call it from the description alone.

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 0%, so the description must carry parameter meaning. It explains match_name lookup and params-key addressing, but it never mentions the required layer_id or the optional name parameter, leaving critical invocation details undocumented.

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+resource: 'Add an effect' and set its parameters. It references find_effects for matching, which helps distinguish lookup from application, but does not explicitly contrast with the sibling edit_effect.

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 directs the agent to use find_effects to obtain the match name, which is useful context. However, it gives no explicit guidance on when to use apply_effect versus edit_effect or apply_preset.

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 destructiveHint=true, non-idempotent, non-read-only, so the safety profile is covered structurally. The description adds a genuine validation constraint (allowed folders) beyond the annotations, but omits what actually gets destroyed or overwritten on the layer and whether existing effects/animation are replaced.

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 sentences with the core action front-loaded and the constraint immediately following. No filler, no repetition 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 two-parameter destructive tool with no output schema, the definition covers the action and one constraint but leaves the mutation's scope undefined (what happens to existing preset/effects on the layer) and gives no indication of the result. Adequate but with clear 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies ffx_path is a filesystem path subject to an allowed-folder restriction, but says nothing about layer_id or path format (absolute vs. relative). Partial compensation for the coverage gap.

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 and resource ('Apply an .ffx animation preset to a layer'), which is clearly distinct from the sibling apply_effect at the resource level. It does not explicitly name apply_effect as the alternative, so it falls short of full sibling differentiation.

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 only guidance is the constraint that the path must be inside allowed folders, which is a precondition rather than a when-to-use rule. Nothing indicates when to prefer this over apply_effect or other animation tools, and no exclusions are 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?

Beyond annotations, the description discloses important behavior: all steps are validated before any execution, a failing step stops the batch with partial results and a batch_id for resume, and each step is its own undo step. These details materially help an agent understand execution semantics for a destructive, non-idempotent batch operation.

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 appropriately sized for a complex batch tool. The core purpose is front-loaded, and each clause adds operational value: substitution syntax, failure behavior, undo granularity, and excluded tools.

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, nested schema, and lack of an output schema, the description covers the important invocation semantics: ordering, limits, validation, failure/resume behavior, defaults, and result substitution. No major behavioral gap remains 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?

The description adds substantial meaning beyond the schema, especially for the steps array: it explains "$N.path" result substitution, step naming via "as", and escaping with "$$". It also clarifies defaults merging behavior, which is central to using the nested step objects 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 states a specific verb and resource: run up to 50 tool calls in order in one call. It also distinguishes the tool from nearby alternatives by explicitly naming preview_frame, run_jsx, and open_project as not appropriate for batching.

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 clearly recommends the tool for multi-step builds and names excluded tools, giving an agent concrete when-to-use and when-not-to-use guidance. This is explicit routing guidance rather than implied usage.

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 convey read-only, open-world and idempotent behavior. The description adds genuine beyond-annotation context: a one-day result cache, a force override, and an environment-variable kill switch. It stops short of noting failure modes (e.g. offline/GitHub unavailable) but covers the key behaviors.

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 purpose, then return contents, then caching/disable caveats. No wasted words; each sentence earns its place, though the caching and disable notes could be a single tighter clause.

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?

No output schema exists, yet the description enumerates the return payload (current and latest versions, update_available, update instructions). Combined with the caching and disabling behavior, an agent has everything needed to call and interpret this 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 0% and the single 'force' parameter is undocumented in the schema. The description partially compensates by implying force bypasses the day-long cache ('cached for a day unless force is true'), but never states the type or that it defaults to false, leaving semantics mostly implicit.

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+resource ('Check whether a newer ae-motion-mcp release exists') and names the mechanism (GitHub version tags). It is unmistakably distinct from all siblings, which are AE project-manipulation tools.

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?

Explains the operational context: default cached result, force to override, and that the tool is disabled when AE_MCP_UPDATE_CHECK=0. There is no meaningful alternative tool to route between, so the lack of explicit exclusions is not a real gap.

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 flag destructiveHint=true and readOnlyHint=false, so safety is covered. The description usefully adds behavioral detail beyond that: it explicitly says target keys are replaced, that easing/tangents/expressions travel with the copy, and how offset/stagger distribute across targets. It does not mention permissions or handling of pre-existing target expressions, keeping it below a 5.

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 plus two clarifying clauses, with no filler. Every phrase (easing/tangents, static value, expression, replacing their keys) earns its place. Dense but readable.

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?

No output schema exists, but the description covers the copy semantics, target semantics, and time-staggering behavior an agent needs to invoke it. The 'same comp' constraint lives in the schema, so the description is adequate without repeating it.

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 17%, so the description must carry the load. It explains to_path (same property type), offset_seconds (shifts keys), and stagger_seconds (i-th target gets i*stagger) — three of six params. path, from_layer_id, and to_layer_ids are left to inference from names, but the value-add over the near-empty schema is real.

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 and resource: copies a property's keys (easing/tangents), static value, and expression to other layers, replacing target keys. An agent can distinguish it from set_keyframes or animate. It stops short of naming any sibling to reinforce the distinction, so it lands at clear-but-not-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: you copy keys between properties/layers. There is no explicit when-to-use, when-not-to-use, or contrast against set_keyframes, edit_keyframes, or stagger, which are the obvious alternatives an agent would weigh.

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, idempotentHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds one genuinely useful non-annotation fact: the new comp is opened in the viewer, which is a UI state change. It says nothing about validation failures, whether the operation is undoable, or how it interacts with an already-open comp.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy. It is arguably too terse for a six-parameter mutation tool, but measured purely as conciseness and structure it is efficient.

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 non-idempotent creation tool with five required, undescribed parameters and no output schema, the description omits units, constraints, project state requirements, and what is returned or changed. The safety annotations carry part of the burden, but the calling contract for the parameters is effectively absent.

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?

Six parameters, five required, with 0% schema description coverage, and the description mentions none of them. Units for fps and duration (seconds vs frames), pixel space for width/height, and the expected range/format of bg_color are all undocumented in both places, leaving the agent to guess.

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?

Clear specific verb+resource: creates a composition, and adds the side effect of opening it in the viewer. It does not differentiate from adjacent tools like set_comp, duplicate_layer or get_comp, so an agent gets the what but not the boundary against 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?

No when-to-use context, no prerequisites (e.g. whether a project must already be open), and no reference to alternatives such as set_comp for editing an existing comp. The agent must infer all of this from the name 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior — refusal conditions and the cascading side effect that force also deletes layers using the item. This is meaningful disclosure beyond the annotations, though it says nothing about error responses or permission requirements.

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 dense sentence that front-loads the action and target, then appends the conditional/override semantics. No filler, nothing repeated.

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 two-parameter destructive mutation with no output schema, the description covers what gets deleted, when it is refused, and what force expands the blast radius to — everything an agent needs before invoking it. Remaining details (idempotency, errors) are either annotation-covered or non-essential.

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 0%, so the description must carry the load. It fully explains force, including its cascading effect, and item_id is understandable from 'project item ... by id'. It is not a perfect substitute for schema-level documentation of id semantics, but it does compensate well.

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 (Delete) and resource (project item) and enumerates the item kinds it covers (comp, footage, folder), which implicitly separates it from the sibling delete_layer. It does not explicitly contrast with delete_layer, so it falls just short of the top band.

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 real conditional guidance: deletion is refused for items used in comps and for non-empty folders, and force overrides that. It stops short of naming alternative tools (e.g. delete_layer, set_item) for those cases, so no explicit 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 mark this as destructive and idempotent, so the agent knows the operation mutates state. The description adds no context about what gets destroyed, whether deletion is reversible, permission requirements, or cascading effects on dependent composites.

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 single fragment is concise but under-specified rather than efficiently informative; it could hold one clause of useful context without bloat.

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 destructive mutation tool with no annotations beyond safety hints and zero parameter documentation, the description is far too thin to let an agent invoke it safely and 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 0%, so the single parameter layer_id is undocumented in both schema and description. The description should clarify what a layer_id refers to and how to obtain it, but provides nothing.

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?

It states a verb (Delete) and resource (layer), which is technically clear. But it does nothing to distinguish itself from siblings like delete_item or set_layer, and the entire purpose is a restatement of the name/title with no added scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as delete_item or set_layer, nor any mention of prerequisites or consequences of 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 mark it as mutating (readOnlyHint=false) but non-destructive and non-idempotent; the description goes beyond that by disclosing the resulting placement (copy above original) and the multiplicative behavior of count and offset_seconds. It does not mention permissions or the returned identifier, but it meaningfully enriches the annotated profile.

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, no waste: purpose and placement lead, parameter semantics follow. Everything is front-loaded and 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 mutation tool with no output schema and 0% schema coverage, the description covers purpose, placement, and the two non-obvious parameters. Gaps remain around the default for name and any return value, but the core call-correctness information is 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?

Schema description coverage is 0%, so the description must compensate. It clearly defines count ('makes several copies') and the tricky offset_seconds ('shifts copy N later in time by N * offset_seconds'); layer_id is self-evident but name remains unexplained.

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 and resource ('Duplicate a layer') and adds the placement outcome ('the copy sits above the original'). This is unambiguous against siblings like add_layer, precompose, or copy_animation, which produce different results.

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 never says when to use this tool versus alternatives such as add_layer or precompose, nor does it state prerequisites. The parameter explanations imply how to use it, but there is no when-to-use or when-not 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 already declare destructiveHint=true and idempotentHint=true, and the 'remove' action is consistent with that framing. The description adds the 1-based indexing convention but says nothing beyond annotations about irreversibility of removal, permissions, or effects on existing state, so it clears the lower annotated bar without exceeding it.

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, front-loaded with the three actions and scoped to 'an effect on a layer,' with the index convention and the lookup pointer appended where they are needed. Nothing is redundant and nothing is buried.

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 not need to explain return values, and it correctly covers the destructive action set, the index convention, and the index source. The remaining gap is that it does not itself describe the layer_id parameter or the effect_index parameter as schema fields, but for a three-parameter tool with an enum this is a minor omission.

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 0%, so the description carries the burden, and it does compensate for the non-obvious part: effect_index is explicitly 1-based and resolvable via get_layer. The action values are self-documenting via the enum and layer_id is unambiguous by name, so all three parameters are effectively covered.

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 gives concrete verbs (remove, enable, disable) tied to a specific resource (an effect on a layer), so an agent knows exactly what it mutates versus the additive apply_effect or delete_layer. It loses the top score only because it never names the sibling it contrasts with, leaving the distinction to be inferred from the verb choice.

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 parenthetical '(see get_layer for the list)' tells the agent where to obtain the effect index, which is real usage context. However, there is no explicit statement of when to use this versus apply_effect (add) or delete_layer, nor any prerequisites, so the guidance remains 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 this as a destructive, non-idempotent mutation, so the description does not need to carry the full safety burden. It adds useful behavioral details such as half-frame key matching, 1-based indexing, set creating or updating a key, move preserving every setting, spatial tangents being relative to the key, and returning the edited keys. It does not explicitly describe delete behavior, which is a minor remaining gap.

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 front-loaded, with no filler. Each sentence conveys operational meaning about scope, key addressing, action semantics, or return behavior.

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 complex nested keyframe-editing tool with no output schema, the description covers core behavior and return values well. However, it omits explicit semantics for the delete action and several nested edit fields, leaving some gaps that the schema alone must resolve.

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?

Although top-level schema coverage is low, the description adds important meaning for core parameters: key addressing by t or index, the half-frame tolerance, set/create/update semantics for t and v, move preserving settings, and spatial_in/out being relative motion-path tangents. It does not cover every nested field such as interp, roving, ease, or auto_bezier, but it substantially compensates for the most ambiguous edit parameters.

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: editing single keys on one property while leaving other keys untouched. This clearly distinguishes it from bulk alternatives such as set_keyframes and from get_keyframes, which is named for 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 gives clear context for when this tool is appropriate: editing individual keys without affecting the rest, and points to get_keyframes for listing all keys. It does not explicitly state when to prefer set_keyframes or other siblings, but the usage context is clear.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds one genuinely useful behavioral fact — results are capped at 50 — but says nothing about matching semantics (case sensitivity, fuzzy vs exact) or what happens on zero matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the verb and resource, with the search fields and the result cap packed in without filler. Nothing is wasted.

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?

There is no output schema, so the description could usefully say what a match looks like (effect name/id/category) for an agent that must feed a result into apply_effect. Combined with the missing matching semantics, this leaves a modest but real gap for a search 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 0% (the lone "query" property is an untyped string), and the description compensates by stating what the query is matched against: display name, match name or category. This is real meaning beyond the bare schema, though it doesn't say whether matching is exact or partial or how multiple terms combine.

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 and resource ("Search installed effects") and names the fields it searches, which clearly separates it from sibling actions like apply_effect, edit_effect and find_fonts. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no statement of prerequisites, and no pointer to related tools such as apply_effect (which would consume a found effect) or find_fonts. The discovery intent is only weakly implied by the word "Search".

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 readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuine value beyond them: the return format (PostScript names) and a version gate (After Effects 24.0+).

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 clauses with the purpose front-loaded, then the requirement note. No filler and nothing redundant with 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?

No output schema exists, and the description supplies the essential return-value context (PostScript names) plus the version prerequisite. The only shortfall is silence on the limit parameter's behavior.

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 50%. The description usefully explains that the query matches against family, style, or PostScript name with examples, supplementing the schema's 'Words that must all match'. However, the limit parameter remains undocumented in both schema and description, so it does not fully compensate for the gap.

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 (search) and resource (installed fonts) plus the three searchable fields (family, style, PostScript name) with examples. It does not explicitly differentiate from the parallel find_effects sibling, though the pointer to set_text clarifies its role.

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 usage context by naming the consumer tool ('returns PostScript names for set_text font') and a prerequisite ('Needs After Effects 24.0+'). It lacks explicit when-not-to-use guidance or a named alternative, keeping it below a 5.

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 the safe read-only, idempotent profile, so the description is free to add operation-specific behavior: layers come back top-first, layer fields are only reported when non-default, and limit defaults to 150. Those are non-obvious traits an agent would not get from the annotations or 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 compact sentences; the return-field list is front-loaded and the paging guidance follows. Every clause carries information, though the telegraphic phrasing ('kind or at', 'kinds counts all layers') costs some clarity for the sake of brevity.

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 usefully enumerates the returned fields and documents paging defaults, so an agent can call it on a large comp without surprises. Remaining gaps are the meaning of comp_id, error behavior for bad ids, and the ambiguous 'kinds counts all layers' note.

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 0%, so the description carries the burden, and it mostly does: name is a substring filter, at is in seconds and means 'layers visible then', limit/offset define paging with a stated default, and kind corresponds to the enum. Only comp_id is left unexplained, and the phrase 'kinds counts all layers' is too terse to be reliable.

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?

Names a specific verb and resource ('Get composition settings and its layers') and enumerates the returned layer fields, which makes the payload concrete rather than tautological. It does not explicitly distinguish itself from close siblings like get_layer or get_project, so an agent must infer the split.

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 conditional guidance for one scenario ('Big comps: filter by name... page with limit/offset'), which tells the agent when to reach for filtering and paging. There is no statement of when to prefer this over get_layer/get_project, and no prerequisites or exclusions above the paging case.

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?

With readOnly/idempotent/non-destructive annotations already covering safety, the description adds real behavioral content: exactly which animation attributes are returned and the edge case that an unanimated property returns its static value. It omits what happens on an invalid path or layer, but the added semantics are meaningful.

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?

Compact two-clause sentence that front-loads the action and return contents, with the helper hint last. The semicolon-clause 'unanimated, its value' is terse to the point of being slightly opaque, but nothing is wasted.

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 usefully describes the shape of the returned keyframe data. However, for a 2-required-param tool at 0% schema coverage, the parameter semantics and failure behavior are left unexplained, so the definition is adequate but not 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 description coverage is 0% for both parameters, and the description never explains the 'path' format (string vs. array of string/number segments) or what layer_id refers to. Pointing at list_properties to obtain a path is the only param guidance, which is indirect and does not compensate for the coverage gap.

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 and resource ('Read all keyframes of one property') and even enumerates the returned fields (time, value, interpolation, temporal ease, expression). It also distinguishes itself from the write-side siblings set_keyframes/edit_keyframes by naming list_properties as the routing helper.

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 actionable context: 'Use list_properties to find the path' tells the agent the prerequisite step before calling this tool. It does not state when to prefer alternatives (e.g. set_keyframes vs edit_keyframes) or exclusions, so it stops short of a full routing statement.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: bounds semantics differ for content vs comp layers, bounds is null for 3D layers, and values are sampled at a given time. It still doesn't say what happens when layer_ids is passed or how missing layers behave.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence plus a short clarifying clause; the key scope ('or several: layer_ids') is front-loaded. The nested parentheticals about bounds make it slightly hard to parse but nothing is redundant.

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 carries the burden of describing returns and it does enumerate the returned fields plus the 3D-null edge case. The remaining gap is the time unit and multi-id behavior, which keeps it short of 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 0%, so the description must compensate. It clarifies that layer_id is singular and layer_ids accepts several, and that time defaults to 0 — useful mapping. However it omits the unit of time (seconds vs frames) and whether the two id parameters are mutually exclusive, which are the most likely sources of misuse.

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 and resource ('Get a layer') and enumerates the data returned (transform, text, effects, expressions, masks, bounds), which separates it from get_comp or list_properties. It never names a sibling to contrast with, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as list_properties or get_keyframes. The only usage signal is the implicit 'this is a read' plus the note that time defaults to 0.

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 the safe read-only, idempotent profile, so the bar is lower. The description adds non-obvious behavior beyond them: the 300-layer truncation with a 'layers_listed: false' flag, the 200-item default page size, and the instruction to relay the update field to the user.

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 dense paragraph that front-loads the primary purpose and the returned fields before dropping into filter/pagination mechanics. Every clause carries information, though the run-on structure slightly reduces scannability.

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 and 0% schema coverage, the description must explain both inputs and outputs — and it does, covering the return shape, truncation semantics, pagination defaults, and the update notice. An agent has everything needed to call and interpret it.

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 0%, so the description carries the full burden. It documents all four parameters meaningfully: name is a substring match, type filters, limit defaults to 200, and offset pages the results — compensating well for the empty 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 verb and resource ('List project items with each comp's layers') and enumerates the returned fields (active comp id, AE version, project path), so the agent knows exactly what comes back. It also distinguishes itself from get_comp by naming that sibling as the fallback when layer data is truncated.

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 conditions for filtering (by name substring or type) and pagination (limit 200 / offset), plus an explicit alternative: when the page exceeds 300 layers, use get_comp instead. No explicit 'when not to use' beyond that, but the routing condition is concrete.

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, idempotentHint, and non-destructive behavior, so safety is covered. The description adds useful detail about what is returned (first character's fields, ranges for differing styled parts), but does not discuss return format or how ranges are structured. It goes beyond the annotations but not richly.

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 dense sentence with parenthetical clarifications, front-loaded with the core action. It is efficient though the long list of style fields may be terse for some agents.

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 and sparse schema descriptions, the description does substantial work by naming returned properties and the ranges concept. It omits error conditions and exact range structure, leaving a small gap for a read tool whose annotations already cover safety.

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 0%, so the description carries the burden. It explains the time parameter ('at time, default: now') and implies layer_id identifies the layer, partially compensating for the empty schema descriptions. No detail on layer_id format or time semantics beyond 'now', but the key parameters are addressed.

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 text layer's content and styling), then enumerates exactly which style attributes are returned. An agent can distinguish this read tool from sibling setters like set_text or get_layer 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?

The description implies usage by noting the default time ('now') and that ranges capture differing parts, but it never states when to use this rather than get_layer or list_properties, nor any prerequisites. Usage context is implied rather than explicit.

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 this is a non-idempotent, non-destructive, non-open-world write, so the safety profile is covered. The description adds real value beyond that by disclosing the atomic validation behavior ('All files are checked before any is imported') and that folder files the imports — behavioral traits not present in the 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?

Dense and front-loaded: the core action leads, then mode semantics, then interpretation params, then the atomicity guarantee. Every clause carries information with no filler, despite the telegraphic style.

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 8-param mutation tool with annotations and no output schema, the description covers the key mode/interpretation semantics and the check-before-import guarantee. It omits failure behavior and the unexplained 'name' param, but the essentials for correct invocation 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?

Schema coverage is only 13% (just fps documented), so the description must carry the load and largely does: it explains as (sequence/comp/comp_cropped), fps/loop/alpha as interpretation settings, folder as the filing target, and path as the sequence's first frame. Only 'name' is left unexplained, a minor gap against 8 params.

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 and resource ('Import a file, or several (paths), into the project') and clarifies the multiple modes via the 'as' enum. It references the sibling set_item as the tool for later interpretation changes, giving partial differentiation, though it doesn't position itself against other import-adjacent 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?

Usage is implied through the 'as' mode explanations (sequence = first frame, comp/comp_cropped = layered PSD/AI) and the note that set_item changes interpretation later. There is no explicit when-to-use vs when-not guidance or stated prerequisites, so the agent must infer the right invocation 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?

Beyond the annotations (destructive=true, idempotent=false), it discloses atomic refusal conditions (self-links, cycles, locked layers, mixed comps rejected before any change) and the subtle side effect that jump=true can visibly move children. These are exactly the mutation risks an agent needs.

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 dense sentences that front-load the primary operation and pack real information into every clause. The opening 'Parent layer_ids to parent_id' is slightly telegraphic, requiring the reader to parse the grammar, but no sentence is wasted.

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 destructive, nested-object, no-output-schema tool, it covers mode selection, side effects, and failure guarantees. It does not describe what is returned or whether the operation is confirmed/reversible, which is a modest remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 25% schema coverage, the description compensates well: parent_id's null-unlink behavior, new_null's average-position and 3D derivation, and jump's transform-preserving semantics are all explained. It leaves new_null.name and new_null.position unexplained, so not a full 5.

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 (parent/link) and resource (layer_ids) plus the two target modes (an existing parent_id or a newly created null). No sibling among the listed tools performs parenting, so the operation is unmistakable 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 distinguishes the three modes: passing a parent_id, passing null to unlink, and supplying new_null to create a parent at the children's average position. It does not name an alternative tool or state prereqs for choosing one mode over another, which caps it below 5.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context by specifying the returned data shape (including keyframe counts and expressions), which matters since there is no output schema, though it omits depth/traversal cost or result-size 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 tight sentences, front-loading what is returned before the usage note. Nothing is padded or redundant.

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 read-only nature is covered by annotations and the return fields are partially described, but with five parameters at 20% schema coverage and a required layer_id documented nowhere, an agent lacks enough detail on traversal scope (depth, time, group_path) to call this precisely.

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 20% and the description contributes nothing about parameters: layer_id (required), time, depth and group_path are all left unexplained in both places. With low coverage the description should compensate, and it does not.

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 ('walk') and resource ('a layer's property tree') and enumerates exactly what is returned (names, match names, value types, values, keyframe counts, expressions). This clearly differentiates it from sibling readers like get_layer or get_keyframes.

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?

Explicitly states when to use it ('to find property paths before set_property / set_keyframes'), naming the downstream tools it feeds. It does not state exclusions or when to prefer an alternative reader, so it stops short of a 5.

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 (readOnly, idempotent, non-destructive, closed-world) match a discovery operation, and the description adds genuine behavior beyond them: the batch-step implicit-reveal behavior, and the fact that scripting/run_jsx requires AE_MCP_ALLOW_JSX=1. It does not state the return shape explicitly, but annotations carry the safety profile.

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?

Front-loaded with the purpose and the routing rule, then a dense but purposeful catalog where every group clause earns its place by documenting parameter values. It is long, but the length is functional rather than padding; a small deduction for density over scannability.

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 discovery tool with no output schema, the description covers what is needed: what it returns (a group's tools and their arguments), when to call it, and the scripting caveat. Nothing critical to correct invocation 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 0%, so the description must compensate — and it does, enumerating every one of the 11 enum group values with the concrete capabilities each contains (e.g. timeline: split, shift, trim, markers; motion: animate with springs, text_reveal, transition, review_motion). This is far richer than the bare enum in 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 verb+resource: it shows a not-yet-listed tool group so the agent can read that group's tool arguments. This is clearly distinguishable from every sibling (which act on AE content rather than on tool discovery), though the name 'load_tools' could superficially be mistaken for invoking tools — the description corrects that. No sibling tool is directly comparable, so there is no explicit contrast to make.

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 context: use it when a group 'is not listed yet' and you need its tools' arguments. It also discloses an alternative mechanism — 'a batch step naming one of their tools shows its group by itself' — so the agent knows when this call is unnecessary. No explicit when-not beyond that, hence not a 5.

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 flag destructiveHint=true, but the description adds the concrete behavior an agent needs: the refusal-on-dirty-state rule, that discard_unsaved permanently loses changes, that the operation 'Cannot be undone', and that the return value mirrors get_project. This goes well beyond what the structured fields convey.

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 dense sentences, front-loaded with the primary action before the refusal rule, and no sentence is filler — each adds operative information (formats, refusal, data loss, return shape).

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 three-parameter mutation tool with no parameter descriptions and no output schema, the description covers the action, the failure mode, the destructive flag, the irreversibility, and the return contract. Nothing an agent needs to call it safely 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 0%, so the description must carry all three parameters — and it does: 'new: true' for an empty project, the path constraint ('inside the allowed folders') for .aep/.aepx files, and the exact semantics of discard_unsaved including its destructive side effect. Minor gap: the 'path' parameter is never named explicitly, only implied by the file-format sentence.

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 (Open) plus resource (After Effects project), enumerates the accepted formats and the empty-project variant, and differentiates itself from siblings by noting it returns 'the new project like get_project' and that it replaces the currently open project. An agent can distinguish it from get_project/save_project without opening any 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?

Explicitly states the condition under which the tool refuses (unsaved changes present), the flag that overrides the refusal (discard_unsaved), and the alternative to use when preservation is wanted ('use save_project first to keep them'). Both when-to-use and when-not-to-use are covered.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real context beyond that: the default for move_attributes, exactly what gets relocated (transforms, effects, masks), and the single-layer restriction when the flag is false.

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 the core action front-loaded and no filler. The nested parenthetical and quoted 'leave all attributes' phrase make the second sentence slightly harder to parse than necessary.

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 destructive, non-idempotent mutation with no output schema, the description answers the key behavioral question of where attributes end up. It omits what the new comp is called (the name parameter) and any note on return value, but the annotations already carry the safety story.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (only layer_ids carries 'Same comp'). The description compensates well for move_attributes, giving its default and the precise meaning of both values, but says nothing about name, which is undocumented in both schema and description. Partial compensation for a low-coverage 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 verb (precompose), the source resource (layers from the same comp) and the outcome (a new comp). No sibling in the list performs this operation, so an agent can distinguish it from duplicate_layer, add_layer or create_comp without opening a 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 scope constraint ('from the same comp') and the conditional rule for move_attributes=false imply when the tool applies, but there is no explicit when-to-use/when-not or named alternative. Guidance is inferred 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/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not: image output costs tokens by size, the tiling layout of a multi-time result, and the recommendation to batch times in a single call. It does not mention rate limits or output format, but the added cost/layout disclosure is substantive.

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 purpose and the cost/batching advice are front-loaded and tight. The final sentence about 'scene / scenes' in an edit does not earn its place — it references concepts absent from the schema and could mislead an agent into looking for non-existent parameters.

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, no-output-schema preview tool, the description covers purpose, output shape (one tiled image), size defaults, and cost trade-offs, which is most of what an agent needs. Remaining gaps are minor (exact image format, max frame count is only in the schema) but the confusing scene/scenes sentence slightly undermines it.

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 67% (comp_id is undocumented anywhere), and the description reinforces the size/time semantics ('keep the default size', tiling order for multiple times). That is helpful but largely restates the schema's own size and time descriptions, and the trailing 'scene / scenes name the precomp each frame shows' refers to parameters that do not exist in the schema, adding confusion rather than clarity.

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 ('Render comp frames and return them as one image') plus the composition mechanism ('several times are tiled left to right, top to bottom'). This clearly separates it from render_start/render_status, though no sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete call-pattern advice ('keep the default size', 'pass several times in one call rather than calling once per time'), which is real guidance on how to invoke it efficiently. However it never states when to prefer this over render_start or the other render tools, and offers no exclusions, so usage is only implied.

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 idempotentHint=true and destructiveHint=false, so the agent knows repeats are safe and no data is destroyed. Beyond that the description adds nothing: it doesn't state what happens to a partially rendered file, whether the call errors when the job is already finished, or whether cancellation is synchronous.

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 short sentence with zero filler and the action front-loaded. It is efficient, though at this length the brevity shades into under-specification.

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 tool with no output schema and annotations covering idempotency/destructiveness, the description is minimally viable but omits caller-relevant details such as error conditions and the fact that job_id comes from render_start.

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?

One parameter exists with 0% schema description coverage, so the description carries the full burden but merely repeats 'job' without clarifying job_id format or where it comes from (presumably render_start). The schema is bare and the description does not compensate.

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 ('Cancel') and resource ('a running render job'), which is unambiguous and clearly distinct from siblings like render_start and render_status. However, it never names those siblings, so differentiation relies on the agent already knowing the render family.

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 when-to-use or when-not guidance, and no reference to the obvious alternatives render_start/render_status. The agent must infer from the single sentence when cancellation is appropriate (e.g., only for in-flight jobs) with no help.

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 destructiveHint=true, non-idempotent, and non-read-only, so the bar is lower. The description adds meaningful behavior beyond that: it saves the project first, runs as a background job, and details what verify/deliver/draft/software do. It still omits what gets destroyed or overwritten and permission requirements.

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?

Front-loads the core action and packs parameter semantics compactly, but the run-on colon-separated clauses and terse shorthand reduce readability. Every clause is informative, so little is wasted.

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 13-param tool with no output schema, the description covers the workflow (save, start, poll), the whole-comp vs work-area scope, and most optional flags. It falls short only on overwrite and explicit parameter naming for the required fields.

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 0%, so the description must carry the burden, and it does for most params (om_template, rs_template, software, verify, deliver, loudness, audio_only, start, end, draft). Only overwrite and the obvious required comp_id/output_path are left unexplained.

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 and resource: it saves the project and starts a background aerender job. It also names the sibling to poll afterward (render_status with the job_id), letting an agent distinguish it from render_status and render_cancel without opening a 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?

Gives clear operational context and explicitly routes the agent to render_status for polling. However, it does not state when not to use it (e.g. preview_frame/review_motion for quick looks) or any preconditions, so exclusions are left 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds real value by disclosing the polling cadence ('poll_after_s (wait that long)'), the state enum, and that the response includes diagnostics like check/errors/hint and log tail. That is meaningful behavioral context beyond the 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?

A single dense sentence that front-loads the most important field (state) and then lists the rest. Given there is no output schema, the enumeration of return fields is largely justified rather than padding. It is telegraphic but 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?

With no output schema, the description carries the burden of explaining the return payload, and it does so thoroughly (state, percent, frames, eta, phase, errors, log tail, file written). The remaining gap is the meaning of job_id and the surrounding workflow with render_start/render_cancel, but for a single-parameter read-only tool this is close to 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 description coverage is 0% and the single parameter job_id is never mentioned in the description, so it does not compensate for the gap. job_id is largely self-explanatory by convention, which keeps this above a 1, but the description adds no semantic detail about what identifier it expects.

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 verb 'Get' plus the resource (render job state) is clear, and the enum running|done|failed|canceled makes the resource unambiguous. It does not explicitly differentiate itself from siblings render_start/render_cancel, but the name and content make the role obvious. The description leans toward enumerating return values rather than stating purpose outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to call this versus alternatives, and no mention of the typical flow (call render_start, then poll render_status). The field 'poll_after_s (wait that long)' only weakly implies a polling loop. No exclusions or prerequisites are given.

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 this is a mutating, non-idempotent, destructive operation, so the safety profile is covered. The description adds useful ordering semantics ('Before means above in the stack') and the mutual-exclusivity rule, but says nothing about required permissions, failure modes, or what a bad combination returns.

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, with the core action and the parameter-exclusivity rule front-loaded. No filler and no redundancy.

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 whose destructive/non-idempotent profile is already given by annotations, the description supplies the parameter semantics and ordering convention an agent needs. Only minor gaps remain (enum meanings in 'to', no error behavior), and no output schema is needed.

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?

With 0% schema description coverage, the description carries the burden and does so well: it names all four optional parameters, clarifies the 'exactly one' constraint the schema cannot express, and defines index=1 as top and the before/after orientation. It stops short of explaining the enum values of 'to' or the meaning of layer_id.

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 and resource ('Change a layer's stacking order'), which is unambiguous and clearly separable from siblings like set_layer, add_layer, and duplicate_layer. An agent can identify the operation 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?

The mutual-exclusivity rule ('Pass exactly one of...') is a genuine usage constraint, but the description never says when to prefer this tool over alternatives such as set_layer or what preconditions apply. Usage is implied rather than framed against 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?

With destructiveHint=true and idempotentHint=true already declared, the description adds real value by disclosing what is preserved ('keeping the layer's timing, keyframes, masks and effects') and the side effect of fix_expressions. It does not spell out what is lost when the source is swapped or any failure/error conditions, leaving a modest gap.

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 tight sentences, front-loaded with the core action, then the fix_expressions behavior, then supported layer types. Every sentence conveys distinct, useful information 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 moderate-complexity mutation with no output schema, the description covers purpose, preservation behavior, parameter semantics, and scope. It omits return value and any preconditions (e.g., type-compatibility between the new item and layer), but is otherwise sufficient 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 0%, so the description must carry parameter meaning. It explains fix_expressions well ('default true, updates expressions that referred to the old source') and implies item_id is the replacement source, but layer_id and item_id are never explicitly defined as target-layer vs new-item, so it only partially compensates.

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 and resource ('Swap the footage, comp or solid a layer shows for another project item') and reinforces it with a concrete analogy ('like Alt/Option-dragging onto it'). This clearly separates it from sibling mutators like set_layer, duplicate_layer, or set_item, so an agent can pick it without opening other 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?

Provides clear usage context via the drag-and-drop analogy and scopes applicability ('Works on footage, precomp, solid and null layers'), which tells the agent when the tool is valid. However, it names no alternative tool and gives no explicit when-not guidance, so it stops just short of full routing help.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context, and it does: it discloses that no render/image is produced, that warnings are the output, and default thresholds (e.g. "default 3% of the comp's short side"). It stops short of describing the return structure or how warnings are organized.

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?

Everything is packed into a single 100+ word sentence with deeply nested parentheses ("(3D: by depth)", "(vertical comps: the top 10%...)"), making the long checklist hard to parse. The purpose is front-loaded, but the structure undermines scanability for a large criteria set that would read far better as a list.

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 6-parameter tool with low schema coverage and no output schema, the description supplies the review criteria and a couple of threshold defaults but omits the meaning of comp_id, max, and all, and never characterizes the returned warnings. Adequate but with visible 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?

With only 17% schema description coverage across 6 parameters, the description must carry meaning, and it partially does: it explains max_hold, min_text (including its default), and that scene=false skips scene checks. However, comp_id, max, and all receive no explanation in either place, leaving clear 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 opening clause states a specific verb (critique) and resource (a comp's animation) and explicitly scopes it as "without rendering (cheap, no image)," which cleanly separates it from render/preview siblings like preview_frame and render_start. No sibling tool shares this review function, so differentiation is implicit rather than stated, keeping it just short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Run after each scene and fix every warning" gives a concrete trigger point in the workflow, which is genuine when-to-use guidance. It does not name alternatives or state when not to run it, so it falls short of the explicit alternatives/exclusions bar for a 5.

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 destructiveHint=true and non-idempotent, but the description goes further: it explains what clean:true destroys (footage no comp uses, with removed_footage count), what snapshot:true creates (numbered copy in snapshots/, labeled by note), and the overwrite semantics. These are exactly the destructive and side-effect details the annotations flag but do not explain.

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?

Dense but front-loaded with the primary action, then branching behavior for path/no-path, then the clean/snapshot modifiers. Every sentence carries information; a small readability cost from the ellipses-heavy style, but no padding.

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 5-param mutation tool with no output schema and no annotation detail, the description covers the branching logic, preconditions, destructive side effects, retention behavior, and the recovery path. An agent has everything needed to choose parameters and anticipate outcomes.

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 0%, so the description must carry the burden, and it does for most params: path triggers Save As, overwrite replaces existing files, clean removes unused footage, snapshot creates a retained copy, note becomes the snapshot label. Only 'note' semantics are slightly implicit, but the overall coverage is strong for a 0%-coverage 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 verb and resource ('Save the project') and distinguishes two distinct behaviors: Save As with path versus in-place save without. This is clearly separable from get_project and open_project in the sibling list.

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?

Explicitly covers the when: with path does Save As, without path saves in place. Notes the precondition that in-place save requires an already-saved project, and links render_start to needing a saved project. Names open_project as the recovery route via snapshots. This is textbook routing 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 already declare the safety profile (destructiveHint=true, idempotentHint=true), so the bar is lower, and the description still adds real behavior: partial-update semantics, the work_area containment constraint, the motion_blur/frame_blending rendering dependency, and the shutter_angle default of 180. It does not explain what the destructive flag implies for existing layers or durations, which is the one notable gap.

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?

Dense and front-loaded: the partial-update rule leads, followed by constraints and defaults in priority order. Every clause carries information, though the semicolon-chained jargon is terse enough to be slightly hard to parse on first read.

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 13-parameter mutation tool with no output schema and zero schema-level documentation, the description covers the highest-risk fields and the update semantics but leaves most parameters and the destructive implications unexplained. Adequate to call safely, not 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 description coverage is 0% across 13 parameters, so the description must carry the load and only partly does: it explains work_area, motion_blur, frame_blending, and shutter_angle's default. fps, name, width, height, bg_color, duration, pixel_aspect, and shutter_phase get no meaning beyond their names, and the nested work_area.start/duration fields are only indirectly covered.

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?

"Change comp settings" gives a specific verb and resource, and the partial-update clause pins down exactly what kind of mutation this is. It reads clearly against siblings like set_layer, set_property, and create_comp, though it never names an alternative explicitly.

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?

"only the fields you pass change" is genuinely useful invocation guidance that tells the agent this is a partial update rather than a full replacement. However, there is no when-to-use vs when-not guidance and no routing away from create_comp or set_item, so usage is only implied.

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, destructiveHint=true, and idempotentHint=true. The description adds real value on top: an empty string clears the expression (the concrete destructive behavior) and that it returns whether AE accepted the syntax. It stops short of stating auth/connection requirements or what happens on rejection.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence with the primary action first, parenthetical clarifications for the two non-obvious behaviors, and no filler. Every clause adds operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully states the return value ('whether After Effects accepted the syntax'). But for a 4-parameter mutation tool with 25% schema coverage, the unexplained 'path' parameter and the absence of any environment/permission prerequisite leave it short of 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 only 25%, so the description must carry more weight. It does explain layer_id vs layer_ids semantics ('send a shared expression once') and the empty-string behavior of expression, but it never explains the required 'path' parameter, which accepts either a string or an array of strings/numbers — the biggest ambiguity in 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 verb (set) and resource (an expression on a property), plus the multi-layer scope, which separates it from set_property. It doesn't name the sibling tool explicitly, so an agent must infer the boundary rather than being told.

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 some usage guidance for the batch path (layer_ids = same property on many layers, shared expression sent once), which implies when to pick it over layer_id. However, there is no when-to-use vs set_property, no prerequisite about an active After Effects connection, and no note on failure behavior.

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 not-read-only, idempotent and destructive. Beyond that the description adds real behavioral detail the annotations cannot: 'file swaps the footage's file for every layer that uses it' (a cross-layer side effect) and 'sequence: file is a sequence's first frame'. It leaves out return behavior and permission requirements.

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 densely packed sentence with no filler and the mutation target front-loaded. It is efficient, though the semicolon-chained clauses make it slightly hard to scan.

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 10-parameter destructive mutation with no output schema, the description covers the operation and most field semantics, including the important side effect on dependent layers. Gaps remain for 'loop', the alpha enum meaning, and error/return behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 10%, so the description carries most of the semantic load and largely succeeds: label range (0-16), folder null = top level, file's swap semantics, sequence's first-frame meaning, and the footage-interpretation grouping of fps/loop/alpha. It still leaves 'loop' and the alpha enum values unexplained, so it does not fully compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Change') and resource ('a project item') and immediately narrows the resource to comp/footage/folder, then enumerates the settable fields. This is enough to tell it apart from set_comp, set_layer and set_property without opening any sibling 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?

Usage is only implied via the field list (name/label/folder = item metadata; fps/loop/alpha = footage interpretation). There is no explicit when-to-use versus set_comp/set_layer, and no stated prerequisites or exclusions.

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

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

Goes well beyond the annotations: it discloses exactly what destruction occurs ('replaced: old keys removed') versus what is preserved ('merge: keep keys at other times'), states the precondition 'Fails if another expression is active', and describes the return value ('Returns the keys as set'). The shape-morph constraint (keep vertex count consistent across keys) is operationally important behavior an agent could not infer from 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?

Dense but front-loaded: the replacement semantics come first, then property-type caveats, then the failure condition, then the return value. Every clause carries information, though the shape-spec sentence is crammed into the middle without visual separation and the abbreviation 'as v' assumes schema familiarity.

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 destructive, 4-parameter mutation with no output schema and no schema descriptions, the description covers mode semantics, destruction scope, a failure precondition, and the return value. The remaining gap is parameter addressing (layer_id and the path identifier format), which an agent needs in order to actually invoke it.

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 0%, so the description must carry the load. It explains the merge flag's semantics, what v means for path properties, and the spring/bounce interp values — but it says nothing about layer_id, the path parameter's string-vs-array addressing form, or the meaning of t. Partial compensation only.

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 and resource ('Replace all keys on a property') and immediately clarifies the two write modes (merge vs. replaced). It is clearly distinct from get_keyframes, but it never names or contrasts with the obvious sibling edit_keyframes, so the agent must infer the boundary.

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 merge/replaced parenthetical gives real guidance on mode selection, and 'interp spring/bounce ... works on any property' scopes a feature. However, there is no explicit when-to-use versus edit_keyframes, no mention of prerequisites such as locking or selection, and the failure condition is stated only incidentally.

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 destructiveHint=true and idempotentHint=true, and the description adds genuine context: partial updates, the cross-layer side effect that solid_color/solid_size alter the solid item for every layer using it, and that audio_fade works under duck_music. It doesn't explain reversibility or why the call is flagged destructive.

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?

Dense but efficient: every clause explains a distinct non-obvious field with no filler, which is proportionate to a 30-parameter tool. The telegraphic semifcolon stream is hard to scan and doesn't group related fields, but nothing is wasted.

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 30-parameter mutation tool with no output schema, the description covers the tricky flags but omits semantics for a substantial set of parameters (timing fields, three_d, adjustment, time_remap, preserve_transparency) and says nothing about permissions, failure modes, or effects on linked properties.

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?

With 0% schema coverage across 30 parameters, the description carries the full burden, and it only explains roughly half (stretch, parent_id, blend_mode, auto_orient, collapse, guide, sampling, solid_*, audio_fade, separate_dimensions). Non-obvious fields such as in/out units, start, time_remap, three_d, adjustment, and preserve_transparency are left undefined.

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?

"Edit a layer; only the fields you pass change" gives a specific verb, resource, and patch semantics that distinguish it from add_layer/delete_layer. It doesn't explicitly compare itself to other property-setting siblings like set_property or set_comp, but 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 patch-semantics line tells the agent it can send a single field without clobbering others, and it flags a real prerequisite: motion_blur/frame_blending require the switch in set_comp too. It stops short of stating when to prefer set_property over set_layer or any ordering/precondition rules.

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?

Adds real behavior beyond the annotations: it discloses that supplying `time` creates or updates a keyframe, and that layer_ids applies the same property to many layers with all targets checked first (pre-validation before mutation). It does not warn that an existing keyframe/static value is overwritten, which matters given destructiveHint=true.

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 short sentences, front-loaded with the core behavior, then the time dependency, then the sibling pointer and the batch caveat. 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 destructive, idempotent mutation with no output schema and 40% schema coverage, the description covers keyframe and batch semantics but leaves the `path` addressing format, overwrite/destructive consequences, and failure behavior underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 40%, but the description compensates for the most misleading params: `time` is defined as the keyframe time and required for animated properties, and `layer_ids` is defined as same-comp multi-layer targeting with upfront validation. `path` format and `layer_id` vs `layer_ids` precedence remain unexplained.

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 (Set) and resource (a property value, static or keyframed) and explicitly distinguishes itself from set_text and from keyframe-only siblings. An agent can tell it apart from set_keyframes/edit_keyframes without opening a schema, since 'creates/updates a keyframe' is called out as a mode of this tool rather than a separate one.

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 a concrete rule ('Animated properties need `time`') and routes text work to set_text. However it does not say when to prefer set_keyframes/batch/animate over repeated calls with layer_ids, nor what to do when a property is animated but no time is supplied.

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 cover idempotence, destructiveness, and open-world, but the description adds meaningful behavior not in annotations: 'skipped: what After Effects refused' discloses partial-failure semantics, and 'New text clears earlier part styling (ranges_cleared)' discloses data loss. However, it doesn't disclose return format degrees of detail or authentication/permission behavior for a 33-param write 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?

The content is dense and front-loaded onto key behaviors, but it's written as run-on sentences with multiple concepts packed into each (semicolons joining unrelated param notes). Not wasteful given 33 params, but readability suffers and a more structured list would 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?

For a 33-param mutation tool with no output schema, the description covers the highest-value semantics (partial failure, range clearing, non-obvious param meanings) but leaves many parameters unexplained and doesn't describe the return/read-back shape beyond 'read back in the result'. It's adequate but not complete for the schema complexity.

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 0% across 33 parameters, so the description must compensate. It does partially: clarifies font as PostScript name, maps leading to disabling auto leading, stroke_color to enabling stroke, horizontal/vertical_scale units as percent, box_size resizing and that point text cannot become box text, time as keyframe, and range match vs start/end semantics with end exclusive. That covers the trickiest params, but many others (tracking, tsume, baseline_shift, indents, ligatures) remain undocumented.

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 ('Set') and resource ('text and styling on a whole text layer') and distinguishes scope from sibling get_text. The agent knows exactly what operation this performs on which object.

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?

Explains key mechanics ('only the fields you pass change', 'pass ranges in the same call' after new text) that guide correct usage. It implies when ranges are needed but never names an alternative tool or states exclusions (e.g., when to use set_property or get_text instead).

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 destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds genuinely useful beyond-annotation detail: every key setting (easing, motion-path tangents) is preserved, and it clarifies operation scope (keys, not layers).

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 tight sentences, front-loaded with the operation and formula, then preservation behavior, then the disambiguation of the nearest alternative. 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 keyframe-mutating tool with no output schema, the description covers the core mechanic, the preservation guarantee, and the scope limitation. It is only slightly short on the 'order' parameter and on permissions/undo behavior expected of a destructive operation.

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?

With 0% schema coverage the description must carry the parameters. It explains offset_seconds via the i * offset_seconds formula, layer_ids by 'across layers', and path as 'one property', but the 'order' enum (forward/reverse) is never mentioned, leaving a documented gap.

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 gives a specific verb (offset/stagger) and resource (existing keyframes of one property across layers) plus a precise formula, layer i shifted by i * offset_seconds. It also distinguishes itself from whole-layer movement, though it names shift_layers/sequence_layers, which are not in the sibling list, rather than the closer siblings like set_keyframes or edit_keyframes.

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 clearly routes the agent: this moves keys, whereas whole layers should use shift_layers / sequence_layers. That explicit when/when-not contrast is strong, but the referenced alternatives are not actual siblings here, so it does little to help the agent choose against the real siblings (set_keyframes, edit_keyframes, copy_animation).

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 destructiveHint=true, readOnlyHint=false, and non-idempotency, so the mutation profile is covered. The description adds useful behavior (per-unit duration/stagger timing, mask clipping, and that it returns the end time) but says nothing about permissions or reversibility.

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?

Four tight sentences with the core verb front-loaded and no filler; the parenthetical and return-value sentence both carry information. Slightly dense but no wasted prose.

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?

It supplies a return value ('end time'), which is valuable since no output schema exists, and explains the animation model. But for an 11-param destructive mutation with no schema docs, several parameters and usage conditions remain unspecified.

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?

With 0% schema description coverage over 11 params, the description must compensate, and it does partially: 'unit by unit' maps to by, 'duration', 'stagger', 'mask', 'phase out: hide' to phase, 'rise/drop' to style, and 'slide' to distance. However, ease, order, time, and layer_id are left unexplained.

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+resource ('Reveal ... a text layer unit by unit') and names the underlying mechanism (text animator + expression selector). An agent can tell it apart from set_text or get_text, though it doesn't explicitly name those 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?

No statement of when to use this vs alternatives like animate, stagger, or transition. Usage is only implied through the mechanic description; no prerequisites and no exclusions are given.

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 and destructiveHint=false, so the agent knows it mutates but is non-destructive. The description adds real behavioral detail about the cut timing ('cut scenes there') and clearing by time + duration/2, plus how iris/bars behave. However, it omits permissions, reversibility, and return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the core action and timing semantics. It's information-rich rather than padded, though the parenthetical layering of the three types makes it slightly run-on.

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 8-parameter mutation tool with no output schema and 13% schema coverage, the description is thin: it explains timing but not most parameters, no prerequisites, no return/result behavior, and no relationship to comp_id/layer context. Substantial gaps remain 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 only 13%, so the description must compensate, yet it only clarifies what 'time' and 'duration/2' mean behaviorally. Parameters like bars, color, center, direction, and type enum are left entirely to the schema with no added meaning (e.g., bar count, color format, center coordinate space).

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 ('add a shape transition') and resource (a transition covering the frame at a given time), and names the three concrete transition types (wipe, bars, iris). It's clearly distinguishable from siblings like edit_effect or add_shape_modifier, though it doesn't explicitly name an alternative.

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 statement of when to use this versus alternatives such as edit_effect or apply_preset, no prerequisites (e.g., requires an existing comp/layer), and no exclusions. The agent must infer usage entirely.

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