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

With no annotations, the description carries the full burden, and 'One undo step' is a genuinely useful behavioral disclosure about atomicity for a mutation tool. It stops there, however: no error behavior for invalid layers, no statement of what is returned (e.g. marker identifiers), and no indication of whether existing markers are affected.

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, fully front-loaded, with the scope rule stated before the undo note. Nothing redundant and nothing that fails to earn 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 three-parameter mutation with a fully documented schema and no output schema, the description covers the essential branching and the undo grouping. The only gap is what an agent can expect back after a successful add, which is minor given the low 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 100%, so the schema already documents comp, layer, and the marker object fields, making the baseline 3. The description only restates the layer-omission rule and adds no syntax or format detail beyond the schema.

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

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

States a specific verb (add) and resource (markers) plus the scope branching: layer when provided, composition when layer is omitted. No sibling in the provided list handles markers, so differentiation is not required and the 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?

Gives clear context for the layer-vs-composition choice ('or to the composition when layer is omitted'), which is the one real usage decision here. It names no alternatives, but no competing sibling exists, so there is nothing more to route against.

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 no annotations, the description carries the full burden and does disclose real behavioral traits: the reveal is driven by a Range Selector that is animated away, mode 'out' mirrors the reveal (last units leave first), layers can be staggered, and critically 'One undo step' tells the agent the operation is a single reversible change. It omits operational behaviors like prerequisites (must text layers exist/be selected) and error handling.

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, then mechanics, then shape/mode semantics. It is dense but every clause maps to a parameter or behavior (shape, mode, offsets, stagger, undo). Slightly long, but no filler sentences.

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 annotations and no output schema, the description explains the animation semantics well but leaves gaps: it never states prerequisites (text layers must exist or be selected), what happens when none are provided, or what the call returns. 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 coverage is already 92%, so the baseline is 3, but the description adds genuine meaning: it explains how 'shape' defaults differ by basedOn (rampUp for characters/words vs square for lines), what 'rampUp' vs 'square' actually do, and that offsets default to position [0,40]/opacity 0/blur 16. This contextualizes the enums and defaults beyond the raw schema text.

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 opens with a precise verb+resource ('Add a text animator reveal') and immediately distinguishes it from the alternative approach ('instead of animating Transform'). It goes further by naming the exact mechanism (Range Selector animated away) so an agent knows exactly what artifact is produced, not just that something is added.

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 the right choice: a motion-design text reveal rather than a Transform/keyframe animation. It does not name sibling tools (e.g. ae_set_property, ae_set_keyframes) as explicit alternatives or state when-not to use it, so it stops short of full 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?

With no annotations, the description carries the full burden and does well: it discloses the marker-writing side effect and its cost ('one undo step'), the time-base conversion when reading a layer source, and the WAV format restriction. It doesn't say whether the analysis itself is read-only or what the returned peak data looks like, leaving some behavioral ground uncovered.

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 purpose, then invocation modes, then the marker side effect. Every clause carries information, though the parenthetical about marker placement is slightly tangled and could be split for readability.

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 nine parameters, the description adequately covers the mode selection, the destructive-ish marker behavior, and the input format constraint. The return shape is only implied via the envelope flag, which is a minor gap for an analysis 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 89%, so the baseline is 3, and the description adds real meaning on top: the path-vs-comp+layer relationship, the comp-time conversion, and the targeting rule for addMarkers (layer, or composition when only path is given) — the latter compensating for addMarkers having no schema description at all.

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 ('Analyze a WAV file') and names the concrete outputs (peak envelope, transient peaks/beats/hits), so the agent knows exactly what comes back. It does not explicitly contrast itself with close siblings like ae_get_audio_info or ae_add_markers, so it stops short of the 5 bar.

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 invocation context for both modes ('Pass path, or comp + layer to use the layer's source file') and a hard precondition ('Only uncompressed PCM/float WAV'). It stops short of 5 because it never says when to prefer this over ae_get_audio_info or ae_add_markers.

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 no annotations, the description carries the disclosure burden and does add real value: it promises the effect's properties are returned for follow-up adjustment and that the operation collapses into 'one undo step', which tells the agent about atomicity and reversibility. It stops short of stating failure behavior when an effect name doesn't resolve or whether duplicate effects stack.

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, zero filler, and the core action and its return behavior are front-loaded before the undo note.

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 annotations and no output schema, the description covers the essential traits: what it mutates, that it returns adjustable properties, and that it is a single undo step. It is slightly thin on the nested settings object and error cases, but adequate to call correctly.

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

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

Schema coverage is 100%, so all five parameters are already documented, including examples for effect and settings. The description's 'display name or matchName' phrasing adds a small amount of vocabulary beyond the schema's plain examples, but nothing about settings syntax or index semantics.

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 ('Apply an effect to a layer') and pinpoints the two accepted identifiers (display name or matchName) plus the optional property-setting behavior. This distinguishes it cleanly from siblings like ae_list_layer_effects and ae_remove_effects.

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

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

The description implies its role (apply and configure an effect) but never says when to prefer it over alternatives such as ae_apply_preset or when to first call ae_list_available_effects to resolve a name. Usage is inferable but not stated.

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

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

There are no annotations, so the description carries the full burden. It usefully discloses the undo footprint ('One undo step'), implying the change is reversible, but says nothing about required file formats beyond the extension, failure modes (missing/incompatible preset), or interaction with the current selection.

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, zero filler, and the core action is front-loaded ahead of the discovery hint and the undo note. Every clause carries information.

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

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

For a mutating tool with no annotations and no output schema, the description covers the essentials (what it does, where to get the preset, undo behavior) but omits error/edge-case behavior and whether a result or confirmation is returned. Adequate rather than thorough.

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

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

Schema coverage is 100%, so all three parameters (comp, path, layer) are already documented in the schema, including the omit-to-use-active-comp behavior. The description only echoes the .ffx path concept, adding no new syntax or constraint detail — the baseline 3 applies.

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

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

The description names a specific verb and resource ('Apply an animation preset (.ffx) to a layer') and explicitly scopes the action to a layer, which is enough to distinguish it from siblings like ae_apply_effect or ae_copy_animation. It also names the related discovery tool, ae_list_presets.

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 routing advice: use ae_list_presets to find the preset path needed by this tool, which is exactly the prerequisite an agent needs. It stops short of stating when NOT to use it (e.g. versus ae_apply_effect), so it is strong but not exhaustive.

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 no annotations, the description carries the full burden and does real work: it discloses the default background-fill behavior for transparent areas and asserts non-destructiveness ('Changes nothing'). It stops short of return-format or auth/permission context, but covers the key behavioral traits for a capture 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?

Three tight sentences, front-loaded with the core action and ending with a one-line safety assertion. Every sentence earns its place with zero 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?

No output schema exists, but the description states it returns an image, and all five params are schema-documented, so an agent has enough to call it. Minor gap: no explicit note on the compareWith side-by-side return or file persistence beyond what the schema says.

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

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

Schema description coverage is 100%, so all five parameters are already documented, making 3 the baseline. The description echoes the background default but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (render one frame of a composition) plus the output form (PNG returned as an image). The singular 'one frame' implicitly distinguishes it from the plural sibling ae_capture_frames, letting an agent choose 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 a purpose ('for visual inspection') that implies when to use it, but never names the obvious alternative ae_capture_frames or states when-not to use this single-frame variant. Usage is left to inference.

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

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

With no annotations, the description carries the full burden and it does well: 'Changes nothing' explicitly declares a non-mutating read operation, and it describes the artifact produced (grid with time labels). It omits any mention of permissions, size/time cost of rendering, or failure modes for an invalid comp/time range.

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: what it produces and why first, then how to specify times, then the safety note. No filler, and the most decision-relevant information is front-loaded.

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, and the description compensates by describing the return artifact as a single contact-sheet image with time labels. Combined with 100% schema coverage on all 9 parameters, an agent has enough to call it correctly; only edge-case behavior (conflicting time arguments, render failures) is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value the schema doesn't: the three mutually exclusive ways to pick frames (explicit times, start/end with count, or step) and the default of 9 evenly spaced. It does not explain interaction rules (e.g., what happens if times and count are both supplied).

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: renders several frames into ONE contact-sheet image with a grid and time labels. The singular sibling ae_capture_frame is implicitly distinguished by 'several frames ... into ONE contact-sheet image', so an agent can tell the two apart 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 a clear use context ('to judge an animation: timing, easing, overlaps, elements appearing outside their containers'), which is exactly the decision the agent needs. It stops short of naming ae_capture_frame or ae_render_preview as alternatives for single-frame or motion-clip inspection, so no explicit 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses that the anchor point is mutated by default, that centering is based on visual content bounds rather than the bounding box, and that the whole operation collapses into 'one undo step' — useful for an agent reasoning about reversibility. Gaps remain: no mention of how expressions or parenting on position/anchor are treated, and no statement of what is returned.

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 compact sentences, front-loaded with the action, then the non-obvious default behavior, then the undo cost. No filler, nothing repeated from the schema.

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

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

For a simple transform tool with no annotations and no output schema, the description covers the action, the default anchor behavior, and the undo footprint — enough to invoke safely. It does not describe return values, which the agent must infer since no output schema exists, and axis values go unexplained in both places.

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 80%, so the schema already documents all, comp, anchor, and layers; the only undocumented parameter is axis. The description adds nuance about the anchor parameter's default (true) and its sourceRectAtTime behavior, but does not compensate for the missing axis documentation. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Center layers in the composition') and immediately explains the mechanism that makes the operation non-obvious (anchor point moved to content center via sourceRectAtTime). No sibling tool performs centering, so there is nothing to differentiate from. An agent can tell exactly what this does.

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

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

The description never says when to reach for this tool versus manipulating position/anchor through ae_set_property, nor does it state prerequisites or exclusions. The only 'guidance' is default-value behavior (anchor defaults to true), which is parameter semantics, not usage 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?

With no annotations, the description carries the full burden and does well: it discloses that keyframes, easing and expressions travel with the copy, defines the stagger formula (offset + n * stagger), notes the replace-before-indexed-group behavior, and crucially states 'One undo step'. It stops short of stating permissions or failure behavior.

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

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

Purpose and the Ctrl+C/V analogy are front-loaded, and each subsequent sentence adds a distinct fact (supported targets, stagger math, undo). It is dense but nearly every clause earns its place, with only mild 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?

A 7-parameter mutation tool with no annotations and no output schema is covered well: behavior, staggering, replace semantics and undo scope are all addressed. The remaining gaps are return value and error/permission behavior, which are secondary here.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the formula 'Target n (1-based in the given order) is shifted by offset + n * stagger frames' explains the interaction of the offset and stagger parameters, and the property-string examples clarify valid path formats.

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 (copy) and resource (a property or whole property group with keyframes, easing and expressions) plus the source-to-target direction. It clearly distinguishes itself from write-style siblings like ae_set_keyframes or ae_apply_preset by being a copy operation across layers.

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 'like Ctrl+C / Ctrl+V' analogy and the enumeration of supported targets (text animators, effects, masks, single properties) give clear usage context. However, it never states when to prefer this over overlapping siblings such as ae_apply_preset, ae_set_keyframes or ae_set_expression, so the routing guidance 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?

With no annotations, the description carries the full burden. It does disclose two useful behaviors beyond the schema: the viewer-opening side effect and that the operation costs exactly 'one undo step', which signals atomicity. However, it omits failure modes (what happens if no project is open), permission/auth needs, and any return-value behavior.

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

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

A single front-loaded clause plus one short parenthetical and a fragment; no sentence is wasted and the core action is stated first.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers the primary action and the viewer side effect but leaves gaps around return values (does it return a comp ID?) and preconditions. It is adequate but not fully self-contained.

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 78%, so the schema documents most parameters (width, height, duration, frameRate, bgColor, pixelAspect, motionBlur) on its own. The description adds meaning only for the undocumented 'open' parameter, clarifying that it controls whether the new comp is opened in the viewer. That is a genuine but narrow addition over 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?

Specific verb ('Create') plus resource ('composition'), clearly distinct from siblings such as ae_set_comp, ae_create_layer, and ae_open_project. It does not explicitly name an alternative, so it stops just 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?

The only usage guidance is implicit via the conditional 'unless open: false', which tells the agent how to suppress the viewer side effect. There is no statement of prerequisites (e.g., whether a project must already be open) or when to prefer this over ae_set_comp for modifying an existing comp.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses 'One undo step' and the default center justification, but omits permissions/auth needs, what happens if no active comp exists, and how the created layer is returned or identified.

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 notable default, then the undo behavior. 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 an 18-parameter tool with no annotations and no output schema, the description is thin: it does not explain that parameters are type-dependent (only some apply per type), what the default name is, or what the call returns. 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 72% and the schema itself already documents per-type meanings for size, shape, fill, font, and color. The description adds only the text center-justification default and implies type-dependent parameter behavior, which is marginal value over 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 (create) and the exact set of resources it can make (text, shape, solid, adjustment, null layer), which cleanly distinguishes it from siblings like ae_create_comp and ae_set_layer.

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

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

Names one alternative with its selecting condition: 'use ae_center_layers to center any layer visually.' That is genuine routing guidance, but it only covers the centering case; there is no broader when-to-use framing or prerequisites (e.g. that a comp must be open).

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 no annotations, the description carries the full burden; it does disclose the read-only nature ('Changes nothing') and what the response contains, which is genuinely useful. It omits edge behavior such as what happens when the layer has no audio or how comp/layer name resolution failures surface.

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

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

A single front-loaded sentence that opens with the resource and then lists the returned fields, ending with the safety claim. No filler, nothing to trim.

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, but the description stands in for one by naming the returned data (path, levels with keyframes, markers). The main gap is that it doesn't distinguish this metadata read from ae_analyze_audio's likely waveform analysis.

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

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

Schema description coverage is 100%, so both parameters (comp, layer) are already fully documented in the schema, including the omit-to-use-active-comp default and 1-based indexing. The description adds nothing beyond that, so the baseline 3 applies.

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

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

It names a specific verb and resource ('Audio info of a layer') and enumerates exactly what that info contains: source file path, audio levels with keyframes, and existing markers. That enumeration separates it cleanly from siblings like ae_set_audio_levels, ae_analyze_audio, and ae_add_markers.

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?

'Changes nothing' implies a safe read-only inspection, so the context is inferable, but the description never states when to reach for this tool versus ae_analyze_audio or ae_get_layer_timing, nor any prerequisites. Usage is implied rather than guided.

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 no annotations, the description carries the full burden. It does disclose the most important trait — 'Changes nothing' establishes this is a non-mutating read. Beyond that it offers no permission requirements, latency, or output-format context, so it is adequate but thin for an unannotated tool.

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

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

Two compact sentences with zero filler; the returned fields are front-loaded and the behavioral note comes last where it belongs. Every clause earns its place.

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

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

For a parameterless-output read tool, the description enumerates the returned timing values so the agent knows what to expect without an output schema, and 'Changes nothing' covers the safety profile. Nothing essential is missing, though it could note what happens if the layer is not found.

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

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

Schema description coverage is 100% and both parameters (comp, layer) are documented in the schema itself, including the 'omit to use active composition' and 1-based index semantics. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description names the resource (layer timing) and enumerates the specific values returned (start, in/out points, duration, source in/out, stretch), so the agent knows exactly what it retrieves. The 'get' verb is implied by the name and the 'Changes nothing' clause. Sibling differentiation is only implicit (contrast with ae_set_layer), so it falls 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?

There is no explicit statement of when to use this tool, when not to, or which sibling to prefer (e.g., ae_inspect or ae_get_selection for broad reads). 'Changes nothing' faintly signals it is safe to call, but no usage guidance is actually 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?

With no annotations, the description carries the full burden, and it does disclose one important trait: this is a non-re-executing read of an existing command's output. It says nothing about behavior when the command is still unfinished, when commandId is invalid, or whether repeated polling calls are safe/expected, so key behavioral questions remain unanswered.

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, front-loaded with the action and scope, then the key behavioral caveat. Zero filler; every clause earns its place.

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

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

For a simple 2-parameter tool this is close, but with no output schema the description should say something about the returned result (payload shape, or how 'not ready yet' appears), and it is silent on that. It is adequate but leaves the agent guessing about the response and failure modes.

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%: waitMs is fully described in the schema, but commandId has no description anywhere. The description implies commandId refers to a previously timed-out command, but adds no format, sourcing, or relationship details (e.g. how waitMs interacts with polling) beyond that implication.

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 names a specific verb and resource ('Fetch the result of a command') and pins the exact scenario ('still running when its tool call timed out'), which no sibling tool covers. It doesn't explicitly name an alternative (e.g. re-invoking ae_run_jsx), relying instead on the implicit 'never re-sends' contrast.

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 trigger condition is stated clearly: use this after a command's tool call timed out while still running. 'Never re-sends the command' also implies the negative case (don't re-run to get the result), but no alternative tool is named and no edge cases (unknown commandId, very old results) are addressed.

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 no annotations, the description carries the full burden and does so with 'Changes nothing', a clear read-only declaration. It also discloses the shape of what is returned (keyframe time/value/interpolation/ease, property trees for groups), which is meaningful behavioral context beyond 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?

Front-loaded with the resource and its contents, followed by usage cues and the read-only note. The return-value enumeration is dense but every clause maps to real output, so little is wasted; the first sentence is somewhat 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?

With no output schema and no annotations, the description compensates well by describing return contents and the read-only guarantee. It omits the empty-selection case (what happens when nothing is selected), which an agent may need to interpret an empty response.

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 single 'depth' parameter is fully documented in the schema (100% coverage), so the baseline is 3. The description references 'property trees for selected groups' but adds no syntax, default, or depth-control guidance beyond what the schema already states.

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 the selection) and enumerates the returned entities precisely: project items, active-comp layers, selected properties with paths, values, keyframes and property trees. This clearly separates it from siblings like ae_get_layer_timing or ae_inspect, which target a single layer rather than the live user selection.

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 explicit triggering context with concrete user phrasings ('this', 'the selected layer', 'look at what I selected'), which is exactly the disambiguation an agent needs. It stops short of naming alternative tools or stating when NOT to use it, so it falls just 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?

No annotations are provided, so the description carries the full burden, and it does disclose a real behavioral trait: 'Does not contact After Effects' tells the agent this is a side-effect-free local read that presumably works without a live AE connection. It stops short of describing return size/format or any bridge prerequisites, but for a static doc fetch this is solid disclosure.

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

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

Two sentences, front-loaded with the verb and resource. The parenthetical topic list is dense but earns its place by letting the agent judge relevance without invoking the tool.

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 and no parameters, so the description must stand alone, and it adequately covers what the tool returns (full guidelines) and when to call it. A note on output length/format would make it complete, but nothing an agent needs in order to call it correctly is 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?

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level detail is required or missing.

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: 'Read the full motion-design and workflow guidelines for this bridge', with a parenthetical inventory of the covered topics (easing, bounce, text animators, stagger, track mattes, motion blur, review loop, ExtendScript pitfalls). This clearly separates it from every sibling, which are all stateful After Effects operations rather than documentation reads.

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?

'Call it once before designing or animating' gives explicit timing and cardinality (once), which is exactly the routing decision an agent needs. The closing clause also signals it is not a substitute for the actual AE action 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: 'Changes nothing,' i.e., it is a read-only, side-effect-free probe. It also previews the returned information, which substitutes for the missing output schema. It stops short of describing failure behavior (e.g., what is reported when AE is not running), so it is not a full 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?

A single front-loaded sentence that leads with purpose and appends the safety note at the end. Every clause earns its place by naming a distinct diagnostic facet, 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?

No output schema exists, so the description usefully compensates by enumerating the fields it reports (versions, running/dialog state, project, comp). For a zero-parameter diagnostic tool this is nearly complete; only the behavior on a failed/disconnected bridge is left unexplained.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already shows.

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 ('Check') and resource (the After Effects bridge) and enumerates the concrete diagnostics it reports: server/runner versions, AE running state or dialog, AE version, open project, active composition. This clearly separates it from the mutation and inspection siblings, which do not report bridge health.

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 rather than stated: an agent can infer this is a diagnostic/troubleshooting probe, and 'Changes nothing' hints it is safe to call. However, there is no explicit when-to-use statement, no mention of when to prefer it over ae_inspect or ae_get_result, and no prerequisites (e.g., whether the bridge must be connected for it to be useful).

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 no annotations, the description must carry the behavioral burden, and 'Changes nothing' is a clear, valuable read-only disclosure not present in structured fields. It also surfaces the default scoping behavior, though it omits anything about return shape or size limits for a tool that returns a deep tree.

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 zero filler; the resource, content, default-scope caveat, and read-only guarantee are all front-loaded.

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 read tool with no output schema, the description conveys purpose, default scoping, and safety adequately. The main omission is any hint of the return payload's size or shape, which an agent might want given the 'deep tree' framing.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented, making 3 the baseline. The description's mention of modifiedOnly mostly restates the schema default and adds no new syntax or format detail.

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 resource ('Deep property tree of a layer or of one of its groups') and enumerates what it contains (values, keyframes, easing, expressions). It clearly reads as an inspection tool, but it never names or distinguishes itself from close siblings such as ae_get_layer_timing or ae_list_layer_effects.

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

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

Usage is only implied: 'inspect' plus the note that only modified properties appear by default. There is no explicit when-to-use statement, no prerequisites, and no routing to an alternative sibling for narrower reads.

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 no annotations, the description carries the full burden. It does disclose the important behavioral fact that the operation is side-effect free ('Changes nothing.'), which is genuinely useful. However it says nothing about result volume, pagination, or ordering despite a 'max' cap.

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, front-loaded sentences with no filler. The search facets and the safety note are packed efficiently, though the second sentence is terse to the point of being cryptic.

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 no-annotation, no-output-schema search tool with an undocumented parameter, the description is adequate but thin. It does not address return shape or the 'includeObsolete' semantics, leaving meaningful gaps an agent would need to guess at.

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 'max' is documented). The description compensates partially by explaining what 'query' matches against (display name, matchName, category), but 'includeObsolete' is left entirely unexplained in both schema and description.

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 (search effects installed in After Effects) and enumerates the searchable facets (display name, matchName, category). It implicitly contrasts with ae_list_layer_effects by scoping to 'installed' effects, but does not name that sibling 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives. An agent must infer on its own whether this is the right tool versus ae_list_layer_effects or ae_apply_effect. The 'Changes nothing.' clause is a safety note, not usage guidance.

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

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

No annotations are provided, so the description carries the full burden. 'Changes nothing' is a useful explicit read-only/no-side-effect disclosure and it hints at the return shape (property tree plus current values), but it does not cover permissions, response size, or error behavior for a missing layer.

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, zero waste, with the resource and return content front-loaded and the safety note trailing. Nothing extraneous.

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

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

For a simple read-only listing tool with no output schema, the description conveys the essential shape of what comes back (effects with their property tree and current values) and affirms no mutation. Minor gaps around error cases and layer resolution are acceptable at this 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 100%, so the schema already documents all four parameters including their defaults. The description's mention of 'property tree' and 'current values' loosely maps to depth/values but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource: list the effects applied to a layer, plus what the listing contains (property tree, current values). This is clearly distinct from sibling ae_list_available_effects, which lists the library of effects rather than those applied to a layer, though the description does not explicitly name that distinction.

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 (inspect what effects already exist on a layer before applying, removing, or setting properties), but no when/when-not condition or alternative is named. An agent must infer the ae_list_available_effects vs ae_list_layer_effects split on its own.

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?

No annotations are provided, so the description carries the burden; it does disclose read-only behavior ('Changes nothing') and the query matching rule (all words must match the path). It omits recursion behavior, case sensitivity, and what happens when no roots are given beyond the default.

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 action and scope, then query semantics, then the read-only reassurance. Nothing 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?

For a 3-parameter read-only lookup with no output schema and no annotations, the description covers purpose, scope, and query matching adequately. Minor gap: results/pagination behavior given the max default is left implicit.

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%: 'roots' and 'max' are documented in the schema, but 'query' has no schema description. The description compensates by defining query semantics ('Words in query must all match the preset path, e.g. blur in'), adding real meaning beyond the schema.

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

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

Specific verb+resource: 'Find animation presets (.ffx)' with the search scope ('standard Adobe preset folders or given folders'). It is clearly distinguishable from siblings like ae_list_available_effects and ae_apply_preset.

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?

'Changes nothing' implies a safe lookup and the description implies use for locating presets, but it never says when to use this versus ae_list_available_effects or the follow-up ae_apply_preset. Usage is inferable but not stated.

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

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

No annotations are provided, so the description carries the full burden. It does add one useful behavioral fact, 'Changes nothing,' confirming a non-mutating read, and it summarizes return contents including the usedIn count semantics. It does not disclose pacing, size limits, or whether output is exhaustive for large projects.

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 with the action front-loaded and no filler. The enumeration of returned fields earns its space by clarifying output, though it runs slightly long for a one-parameter read tool.

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 present, the description must shoulder return-value explanation, and it does so partially by naming the fields returned. For a simple one-optional-param list tool this is close to complete, though it omits ordering or depth details.

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

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

Schema description coverage is 100%, so the single 'items' parameter is already documented with its default. The description reinforces what 'other items' means (folders, footage, solids), but adds no syntax beyond what the schema supplies, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('the open project') and enumerates what the result contains (compositions, layers, folders, footage, solids). It cleanly distinguishes from write-oriented siblings like ae_save_project or ae_create_comp, but does not explicitly differentiate itself from inspection siblings such as ae_get_selection or ae_inspect.

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: you'd call this to survey the open project's contents. There is no explicit when-to-use or when-not guidance, and no routing toward alternatives like ae_get_selection or ae_inspect, so the agent must infer the choice.

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 no annotations the description carries the full burden, and it discloses two important behavioral traits: that opening closes the current project, and that unsaved changes force a save/discard decision. It does not describe success/failure behavior or what happens if both flags are omitted or both set, so it stops short of fully transparent.

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, each earning its place: purpose, the conditional requirement, and the sibling routing. Front-loaded with the core action and 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 mutation-style tool with no output schema and no annotations, the description covers the key danger (closing the current project) and the save/discard requirement. It omits return values and edge-case handling for conflicting flags, leaving a small but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by framing save/discard as a required choice contingent on unsaved state, rather than merely listing them. It still doesn't clarify mutual exclusivity if both are passed, 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?

States a specific verb+resource ('Open an .aep project in After Effects') and immediately clarifies the side effect of closing the current project. It goes further by naming the sibling it replaces (ae_run_jsx), letting an agent differentiate it 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?

Explicitly says to use this instead of opening/closing projects via ae_run_jsx and gives the reason (it breaks AE's undo history). It also states the conditional condition under which save/discard must be supplied. Both when-to-use and the alternative are spelled out.

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 no annotations, the description carries the full behavioral burden. It usefully discloses transactionality ('One undo step'), which tells the agent the operation is grouped atomically, but it omits error behavior (e.g., missing effect name), permission requirements, and what the call 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?

A single sentence plus a two-word fragment; the selector options are front-loaded and no words are wasted. Ideal size for a simple mutation.

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 4-parameter mutation with no output schema or annotations, the description resolves the main ambiguity (targeting a specific effect vs 'all') and states undo behavior. Only the failure/return semantics are left unstated.

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 50%, and the description compensates for exactly the undocumented parameters: it explains that 'effect' accepts a name, matchName, index, or an array of them, and that 'all' removes everything. That is real added meaning beyond the bare schema types.

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 ('Remove effects from a layer') and immediately narrows the selector space ('by name, matchName or index... or all'). It is clearly distinguishable in intent from siblings like ae_apply_effect and ae_list_layer_effects, 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?

The description never states when to reach for this tool versus alternatives such as re-applying a preset or using ae_set_layer. The 'or all' clause implies a bulk-removal mode but does not explain when each mode is appropriate or what preconditions exist.

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 no annotations, the description carries the full burden and does well: it discloses that other queued items are paused and restored, that it blocks After Effects, and that long renders return a commandId for ae_get_result. It does not state whether existing output files are overwritten or any auth/permission requirements, keeping it at a 4.

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 with zero waste, front-loaded with the purpose and followed by side effects and async behavior. Every sentence earns its place.

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

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

Given no annotations and no output schema, the description covers purpose, output formats, queue side effects, blocking behavior, and the async follow-up path. It leaves the start/duration semantics and file-overwrite behavior unexplained, so it is strong but not fully 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 71%, so most params (comp, half, path, format, timeoutMs) are already documented by the schema. The description hints at the time range ('or a time range') but sheds no light on the undocumented 'start' and 'duration' params, so it adds little beyond the schema.

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

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

Clear specific verb+resource: 'Render a composition (or a time range) through the Render Queue to an H.264 MP4 or a PNG sequence.' This distinguishes it well from the still-capture siblings (ae_capture_frame/ae_capture_frames), but it never explicitly contrasts with them, 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?

Usage is implied by 'for the user to watch' (i.e., when you need a viewable preview) and the guidance to poll ae_get_result for long renders. However, there is no explicit when-to-use versus ae_capture_frame, no prerequisites, and no 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?

With no annotations, the description carries the full burden and does so well: it discloses the return semantics (last expression's value, AE objects as short summaries), atomicity ("the whole call is one undo step"), and the async timeout contract (a commandId is returned and must be fetched with ae_get_result, not re-sent). These are exactly the non-obvious behaviors an agent needs before invoking a code-execution 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?

Purpose is front-loaded in the first sentence and each following sentence adds distinct value (return value, args, helper catalog, undo atomicity, timeout recovery). The dense helper-list is the only slightly listy stretch, but it is informative rather than 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?

There is no output schema, so the description correctly explains return values itself, and it also covers runtime constraints, the args channel, available helpers, atomicity, and the timeout/recovery path. An agent has everything needed to call it correctly; only sibling disambiguation 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining that `args` is exposed to the code as the `args` variable and that timeoutMs governs when a commandId is returned. That is value beyond the schema, though `code`/ES3 constraints are already restated 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 and resource ("Run arbitrary ExtendScript inside After Effects") plus the runtime dialect (ES3), so an agent immediately knows what executes. It does not explicitly differentiate itself from the sibling ae_run_jsx_file, which is the obvious near-twin, 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 operational guidance -- pass data via `args` rather than pasting, and fetch results with ae_get_result after a timeout instead of re-sending -- which is genuinely useful. But it never states when to reach for this versus ae_run_jsx_file or the many high-level siblings (ae_set_property, ae_create_comp, etc.), so selection guidance 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?

With no annotations, the description carries the full burden. It usefully discloses 'One undo step' (undo grouping) and that args are optional, but says nothing about the risk profile of executing arbitrary on-disk code, permission requirements, timeout behavior, or error handling.

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

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

A single, front-loaded sentence that states the action, the source of the script, the optional argument, the sibling relationship, and the undo semantics with no filler. 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?

For a tool that executes arbitrary on-disk code with a nested-args parameter, no output schema, and no annotations, the description omits how results are retrieved (e.g., via ae_get_result), timeout semantics, and failure behavior. Coverage is too thin 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 coverage is 33% — only `path` is documented in the schema, leaving `args` and `timeoutMs` undocumented. The description mentions `args` exists but never explains what it does, how it is passed to the script, or what `timeoutMs` controls, so it 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: 'Run an ExtendScript .jsx/.js file from disk'. The parenthetical 'a library of reusable scripts' plus 'like ae_run_jsx' lets an agent infer this is the file-based counterpart to the inline-script sibling, though the contrast is implied 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?

Says the file is 'a library of reusable scripts' and that args are optional, implying a use case, but never states when to choose this over ae_run_jsx or what prerequisites (file must exist on disk, readable by the host) apply. Usage is left to inference from the name.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the two distinct write modes, but a save operation's most important trait — that it overwrites the target file, and what happens on an invalid or non-absolute path — is not mentioned, nor are any return or error signals.

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 primary action front-loaded and the branching behavior immediately after. Every clause carries information; there is no filler or restated 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 one-parameter persistence tool with no annotations and no output schema, the description covers the essential decision an agent must make. It is slightly incomplete on failure behavior and overwrite semantics, which matters for a save-as write, but 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 coverage is 100% and the single parameter is already documented as "Optional absolute .aep path", so the baseline would be 3. The description earns an extra point by explaining the consequence of supplying versus omitting the parameter, which the schema alone does not convey.

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

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

Specific verb+resource ("Save the open project") with the two operating modes spelled out, including the Save As variant. No sibling tool in the set performs saving, so there is no ambiguity to resolve, and the agent can tell instantly that this is a project-persistence call rather than a creation or open call.

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

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

The description gives the condition that selects each behavior: no path means save in place, an absolute .aep path means Save As. It stops short of naming alternatives or stating exclusions (e.g., what to do for a first-time save of an unsaved project), so it is clear context rather than full 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?

With no annotations, the description carries full burden. It usefully discloses that the operation is grouped into 'One undo step', but omits prerequisites (does the layer need to be an audio layer? is an active comp required?) and what happens to existing levels/keyframes when overwriting.

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 primary action front-loaded and the undo note trailing efficiently. Nothing is wasted, though it is sparse rather than rich.

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 7-parameter mutation tool with no annotations and no output schema, the description covers purpose, modes, and undo behavior but leaves open layer-type requirements, active-comp dependency, and stereo left/right handling. 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 coverage is 71% (mid-range), so the schema documents most fields. The description still adds real interpretation beyond the schema by framing the mutually distinct modes: a bare level (static), level+time, or a keys array, plus the dB unit semantics.

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 ('Set Audio Levels (dB) of a layer') and enumerates the three operating modes (static, at a time, keyframes). It distinguishes itself from generic setters like ae_set_property by scoping to audio levels, though it never names 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 mention of 'static, at a time, or as a list of keyframes' implies the three invocation patterns an agent can pick, which is genuine usage context. However, there is no explicit when-to-use/when-not guidance or routing against ae_set_property or ae_set_keyframes.

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 no annotations, the description carries the full burden, and it does disclose two real traits: 'One undo step' (undoability) and the viewer side effect of open: true. However, for a 13-parameter mutation tool it never says whether omitted fields are left untouched (partial vs. full replace), which is the single most consequential behavior 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?

A single, front-loaded sentence that leads with the verb and resource, then enumerates targets with semicolons for easy scanning. Dense but every clause maps to a real parameter; 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 mutation tool with zero annotations, no output schema, and 13 all-optional parameters, the description is only partially complete: it lists what can change and notes the undo cost, but omits the partial-update contract and any permission/state prerequisites. Adequate but with a clear, agent-visible gap.

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

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

Schema description coverage is only 31%, so the description must compensate, and it largely does: it groups width/height as 'size', workAreaStart/workAreaDuration as 'work area', and maps 'current time' to the time parameter, covering nearly all 13 fields conceptually. It stops short of adding semantics beyond naming (e.g., units for duration or frame rate), which the schema also omits.

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 ('Change') plus resource ('composition settings') and an enumeration of exactly which settings: size, duration, frame rate, background color, motion blur, shutter angle, work area, current time. It distinguishes itself from ae_create_comp by verb alone, though it never names that sibling 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?

Usage is implied rather than stated: 'Change' signals a modify-existing-comp operation, and 'open: true opens it in the viewer' hints at a variant workflow, but there is no when-to-use/when-not framing and no mention of ae_create_comp as the alternative for new comps. The 'omit to use the active composition' hint lives in the schema, not the description.

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?

No annotations exist, so the description carries the burden and it does add genuine behavior: it reports expressionError when AE rejects the expression, and the operation collapses into one undo step. It still omits whether partial application can occur or whether the property must already exist, but the error and undo semantics are valuable disclosure.

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, zero filler, with the action and the removal semantics front-loaded ahead of the error and undo notes.

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 4-param mutation tool with no annotations and no output schema, the description covers the operation, the removal path, error signaling, and undo scope. Only minor gaps remain (preconditions on the target property, what the result payload contains).

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 75% and the schema documents comp/layer/property paths well. The description adds semantics the schema lacks for the undocumented 'expression' parameter: an empty string is the removal sentinel, which an agent cannot infer otherwise.

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 ('Set an expression on a layer or effect property') plus the removal mode, which separates it from the sibling ae_set_property. It does not name the sibling explicitly, but the resource ('expression') is distinct enough that an agent can route correctly.

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?

Conveys how to remove an expression (empty string), which is real usage guidance, but gives no explicit when-to-use vs ae_set_property or ae_run_jsx, nor prerequisites (e.g., property must exist, comp/layer resolution context). Usage is implied rather than framed.

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 no annotations, the description carries the full burden. It does add real behavioral context with 'One undo step,' telling the agent the whole call is a single reversible transaction, and the replace semantics imply destructive behavior. It stops short of stating return behavior, permission needs, or error conditions for a mutation 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 action, then dense parameter semantics, then the undo note. Given the seven parameters and the interpolation vocabulary, the length is justified and there is little filler, though the ease/easeIn detail is packed tightly into one long 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 and no annotations, so the description must stand alone for a 7-parameter mutation tool. It covers purpose, ease semantics and undo, but omits return values, error behavior, and how replace interacts with existing keyframe selection, leaving gaps for a tool of this 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 100%, so the baseline is 3, but the description goes beyond the schema by explaining that influence defaults to 33.3, that 'easy' means Easy Ease, that easeIn/easeOut take {speed, influence} objects, and by listing the spatial-only keys (spatialAutoBezier, roving, inTangent, outTangent) not present 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 ('Add keyframes to a layer or effect property') plus a secondary effect ('set their interpolation'), which distinguishes it from the value-setting sibling ae_set_property. It does not name any sibling explicitly, so it stops short of full 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?

Usage is implied by the domain — you call this when you need to create or re-time keyframes — but there is no explicit when-to-use versus ae_set_property or ae_copy_animation, and no exclusions or prerequisites are stated. The rest of the description is ease syntax, not usage 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?

With no annotations, the description must carry the behavioral burden. It adds two genuinely useful facts: keyframe-writing via 'time' and atomicity ('One undo step'). However it omits permission requirements, whether omitted fields are preserved, and any return/error behavior for a 29-param mutation.

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

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

Front-loaded correctly with the verb and the field list, and the keyframe/undo hints come last. But it is one long sentence stuffed with parenthetical sub-clauses, which is dense without being structurally scannable.

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 29-parameter mutation tool with no annotations and no output schema, the description is only partially complete: it never mentions comp scoping, matte behavior, or motion blur, all of which are real parameters. The 'one undo step' note is the strongest completeness contribution.

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 59% (moderate). The description enumerates roughly 20 of 29 fields, adding a grouping ('text' sub-fields) that helps, but it omits motionBlur, trackMatte, trackMatteType, matteVisible, comp, and the timing fields. It neither compresses the uncovered half nor clarifies ambiguous ones beyond the schema.

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

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

States a specific verb ('Change') plus the resource ('layer settings and transform') and enumerates the mutable fields, so an agent knows this is the catch-all layer mutation tool. It does not explicitly distinguish itself from siblings like ae_set_property or ae_set_keyframes, which is the only reason it falls 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?

'Pass time to write keyframes instead of static values' gives one concrete usage rule, but there is no when-not guidance and no routing to alternatives such as ae_set_keyframes, ae_set_property, or ae_add_text_animator despite clear overlap. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden. It usefully discloses the keyframe-vs-static constraint and that the call is 'One undo step,' which is real behavioral context. It omits error behavior, permission/active-composition requirements, and what happens on a type mismatch.

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 action and followed by the two most decision-relevant constraints (keyframe rule, undo behavior). Every sentence earns its place 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 mutation tool with no annotations, no output schema, and full parameter documentation, the description covers the essential behavioral traits an agent needs: path targeting, keyframe semantics, and undo granularity. Only error/edge-case handling is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly (comp, time, layer, value, property). The description adds only the 'by path' framing and ties time to keyframe creation, so baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Set any property of a layer or of its effects by path,' which clearly conveys the operation. It does not, however, explicitly disambiguate from siblings like ae_set_keyframes or ae_set_expression, leaving the boundary to be inferred.

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 usage condition: 'With time, sets a keyframe; without time the property must have no keyframes.' This tells the agent when each mode applies. It stops short of naming alternative tools (e.g. ae_set_keyframes) for the keyframe workflow.

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