surehand-mcp

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

Annotations declare non-readonly and non-idempotent; the description reinforces this by saying each call adds another layer and where it lands (on top unless moveToIndex). It also discloses the return payload (new layer's index, id and name), which the annotations cannot express. It stops short of noting undo/recovery or that the target comp must be open.

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

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

Four sentences, front-loaded with the layer-kind enumeration before the placement and return behavior. Dense but every clause carries information (sibling routing, defaults, return shape); the parenthetical asides are the only minor clutter.

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 27-param creation tool with no output schema, the description covers the return value, default placement, and conditional parameter applicability. Missing only ancillary context such as permission/open-project prerequisites or the undo path, which is a modest gap rather than a blocker.

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 all 27 parameters are individually documented, so the baseline is 3. The description adds cross-parameter semantics the schema cannot: text options apply only to text layers, moveToIndex overrides default top placement, and shape layers are created empty. That grouping genuinely helps the agent pick valid parameter subsets for a 27-param tool.

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 (one layer to a composition) and enumerates the supported layer kinds: solid, text, shape, null, adjustment, camera, light, item. It explicitly carves out the empty-shape case to ae_add_shape, so an agent can separate this from the shape sibling 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?

Names the alternatives and the conditions that select them: use ae_add_shape to draw into an empty shape, ae_set_text to edit existing text, ae_set_layer_attributes (via ae_call) for switches/timing/parent. It also tells the agent that each call adds exactly one layer and lands on top unless moveToIndex is given, which is the key routing decision between repeat calls.

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

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

Beyond the annotations, it explains that a new shape group is created, existing groups are preserved, coordinate positions are layer-relative, new layers are centered in the comp, and it returns the layer and new group. It does not elaborate on non-idempotency or permission requirements, but the annotations already establish the mutation and safety profile.

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

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

The description is front-loaded with the core operation, then adds coordinate semantics, return values, and the mask alternative in a compact sequence. Every sentence contributes actionable information without redundant restatement of schema defaults.

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 17-parameter mutation tool with high schema coverage and no output schema, the description covers layer targeting, coordinate behavior, return values, and the key alternative tool. Nothing essential about invoking it correctly appears to be 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?

The schema already documents 94% of the 17 parameters, so the baseline is 3. The description adds useful semantic context about coordinate positioning relative to the layer and the comp-center convention for new layers, which is not fully captured by the schema alone.

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 the specific action (draw a shape) and enumerates the shape types, fill/stroke support, and whether it creates a new shape layer or adds to an existing one. It also explicitly distinguishes itself from ae_add_mask for cut-out operations.

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

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

The description states when to use an existing layer versus creating a new one, notes that existing groups are kept, and names ae_add_mask as the alternative for cutting out part of a layer. This gives clear routing guidance without leaving the agent to infer alternatives.

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

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

Annotations already declare readOnly=false and idempotent=false, but the description adds substantive behavior: each call appends a NEW instance at the bottom of the stack, unknown names fail with suggestions, and the return payload (stack index, parameters, values set) is disclosed. That is exactly the non-idempotent side effect an agent needs to know before calling.

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 and its preferred argument form, followed by side-effect behavior, return shape, and sibling routing. Dense but nearly every sentence earns its place; the final parenthetical '(both via ae_call)' is a minor aside that could be trimmed.

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

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

No output schema exists, yet the description explains the return value (stack index, parameters, set values) and the failure mode (unknown name with suggestions). Combined with 100% schema coverage and full sibling routing, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so all five parameters are already documented in the schema, including match-name vs display-name semantics. The description reinforces match-name preference with examples but adds no new syntax or constraints, and the optional `name` and `params` merging behavior is only briefly touched. 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 ('Apply an effect to a layer'), lists concrete match-name examples, and names the display-name alternative. An agent can distinguish it from ae_set_effect_params and ae_list_available_effects purely from the description.

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 routes the agent: check parameter names with ae_get_effect_params first, use ae_set_effect_params to change an applied effect, and ae_list_available_effects to search installed effects. The when-to-use and when-not-to-use cases are both named.

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

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

Annotations already mark this as destructive, non-read-only, non-idempotent, and open-world, and the description adds important batch semantics: all steps form one undo step, atomic rollback happens by default, and failures return the failing step's error. This adds meaningful behavioral context beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core batch behavior, then covers atomicity, usage guidance, and exclusions. It is dense but appropriately sized for a complex orchestration tool, with no wasted 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 complex batch tool with no output schema, the description explains the return model as one change report, the atomic rollback behavior, and the failing-step error behavior. Combined with the fully described schema, it gives an agent enough context to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description still adds useful meaning by explaining that each step is a tool plus arguments, that any project/comp/layer/property/keyframe/effect/text/footage tool is allowed, and that ae_run_script is a special step form.

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

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

The description states a specific verb and resource: running many tool steps in one batch call. It clearly distinguishes this from calling a single edit tool directly and explains the step structure, so an agent can identify the tool's role among siblings.

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

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

It explicitly says to use this for repetitive or multi-part edits, to call tools directly for a single edit, and names tool categories that cannot be used as steps. These are clear when-to-use, when-not-to-use, and alternative-selection instructions.

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

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

Adds real context beyond the annotations: the call gets the same validation, permission checks, change report and activity log as a direct invocation, and malformed arguments return an error enumerating them. It does not restate the destructive/openWorld hints or warn that destructive consequences are inherited from the target tool, which is the one behavioral nuance an agent would still have to infer.

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

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

Four short sentences, front-loaded with the purpose, then discovery, then the equivalence guarantee, then the exclusions. No filler; each sentence carries a distinct instruction.

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

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

For a generic dispatcher with a free-form nested args object and no output schema, it covers discovery, error behavior, and parity with direct invocation well. The return shape (presumably the target tool's result) and any depth/recursion limits are 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 100% and both parameters are described in-schema, so the baseline is 3. The description does point to ae_tools {describe} for resolving the free-form args object, which is useful routing but not semantic detail about the arguments themselves.

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 any After Effects tool by name with its arguments — and immediately scopes it to tools listed by ae_tools that aren't loaded in the chat. An agent can distinguish it from ae_batch and the direct per-tool siblings without opening any schema.

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

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

Gives explicit when-to-use (tools not loaded in this chat), explicit when-not-to-use ("Tools loaded in this chat don't need it: call them directly"), and names the discovery path ae_tools {describe: [name]} to obtain the target parameters. Both the positive and negative routing decisions 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?

Goes well beyond the annotations: restore never overwrites the original or an earlier restore, retention is capped at the 50 latest, restore-without-id defaults to the latest, and the unsaved-changes guard is disclosed. The destructiveHint=true annotation is consistent with discardChanges discarding unsaved edits rather than with overwriting files.

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 enumeration and the safety rule before the operational details. It is dense with nested parentheticals, which costs a little readability, but essentially every clause carries operational information.

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

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

No output schema exists, and the description compensates by stating what save returns (id and file) and what list returns (ids, times, labels). Preconditions, defaults, retention and side effects are all covered for a 4-parameter, three-mode tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: omitting `id` on restore selects the latest, `discardChanges` overrides the unsaved-changes refusal, and `label` is only meaningful for save. Only the exact id format is left to 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?

Names the resource (project checkpoints) and enumerates the three concrete operations with verbs: save, list, restore. The parentheticals define what each verb actually does (save = save project then snapshot; restore = opens a NEW file), so it is clearly distinguishable from siblings like ae_undo.

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 an explicit when-to-use rule ('Use before large or risky changes'), a prerequisite ('The project must have been saved once'), and routes the agent elsewhere for the adjacent case ('To revert just the last edits use ae_undo'). It also states the restore precondition (refuses with unsaved changes unless discardChanges).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to re-establish basic safety. It adds useful context beyond the annotations: the comp is empty, it opens in the viewer by default, names need not be unique, and the returned id should be used in later calls. It does not discuss failure modes or permissions, but with annotations covering the core safety profile this is a strong 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?

The description is three dense sentences with no filler. The core creation behavior is front-loaded, followed by return-value guidance and then the sibling alternatives.

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 explains exactly what is returned ('the new comp's id, name and settings') and how to use the id in subsequent calls. It also covers defaults, follow-up layer creation, and alternative tools for copying or precomposing, leaving no essential gap for correctly invoking or chaining this tool.

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

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

Schema description coverage is 100%, so the input schema already explains every parameter including defaults and ranges. The description adds only the name-non-uniqueness caveat and the id-return workflow, and does not elaborate on dimensions, duration, frame rate, or folder targeting beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a precise verb and resource: 'Create a new, empty composition in the open project', and immediately states the default viewer behavior. It clearly distinguishes creation from copying an existing comp or precomposing layers by naming ae_duplicate_comp and ae_precompose as alternatives.

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

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

It gives explicit sequencing guidance ('Then add layers with ae_add_layer / ae_add_shape') and states when to use the alternatives: ae_duplicate_comp for copying an existing comp and ae_precompose for moving existing layers into a new comp. The default behavior and follow-up path leave little ambiguity about when and how to use this tool.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, and the description reinforces this. Beyond annotations, it adds useful behavior: returned paths include values and expression errors, limit truncation sets 'truncated', and the tool requires a query or filter. It does not cover permissions or output structure in exhaustive detail, so a 4 is appropriate.

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

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

The description is dense and front-loaded: use case, scope, examples, return behavior, filters, constraints, and the sibling alternative are all stated without repetition. Every sentence adds actionable information for an agent.

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 compensates by explaining that results include ready-to-use paths, values, expression errors, and truncation state. With six fully described parameters and clear usage guidance, an agent has enough information to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter well. The description adds meaningful framing about what query matches, what the animated/expression filters do, and that limit truncation is signaled, which goes beyond the individual schema fields.

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

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

The description uses a specific verb and resource ('Search every layer of a comp... for properties') and clearly states what the tool returns. It also distinguishes this tool from the sibling browse tool by naming ae_get_properties as the alternative for browsing a layer's tree.

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

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

It explicitly states when to use this tool — 'when you know a property's name but not its layer or path' — and names the alternative for browsing a single layer's tree. It also states the prerequisite that a query or filter is required, preventing misuse.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so "Read-only" is largely redundant, but the description adds genuinely new behavior: large comps are paged and the response carries totalLayers and nextLayerOffset. It does not explain what markers or switches contain, but the core operational behavior is disclosed.

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

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

Three sentences, front-loaded with what is returned, then paging, then disambiguation. The parenthetical field list is dense but informative, and no sentence is 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?

There is no output schema, so the description has to describe returns, and it does so at the field-name level plus pagination guidance. It stops short of explaining the shape of settings/markers or default page size interplay, which leaves a minor gap for a zero-required-param read tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by tying layerOffset/layerLimit to the paged result fields rather than restating them. includeLayers is only implied through "summary of its layers," which is why this is not a 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 and resource (get comp info) and enumerates exactly what comes back: settings, markers, and a layer summary with index, id, name, type, timing, parent, switches. It is clearly differentiable from ae_get_layer_info and ae_get_comp_map, which are named for their narrower scopes.

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 routing: use this to see what a comp contains, ae_get_layer_info for one layer in full, ae_get_comp_map for nested precomps, parenting and expression links. It also states when to page and which result fields drive pagination (totalLayers / nextLayerOffset).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the redundant 'Read-only' line adds little; however, the description does disclose the analytical scope of the call (static dependency analysis across precomps, mattes, expressions) which tells the agent what class of information it will get. It stops short of noting cost on heavily nested comps or how depth truncation is reported.

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

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

One dense but well-ordered sentence describing outputs, then a short routing sentence. Every clause earns its place; the purpose is front-loaded before the alternatives.

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

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

With no output schema, the description carries the burden of describing return content and does so by enumerating the data categories an agent will receive. Combined with explicit sibling routing and fully documented parameters, nothing needed for 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 already documents the comp id/name/'active' semantics and the depth default of 4 with its 1-10 range. The description adds no parameter guidance 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?

States a specific verb+resource ('Overview of how a composition is built') and enumerates exactly the structures returned: nested precomp tree with usage counts, parenting chains, track mattes, and expression cross-references. This is clearly distinguishable from ae_get_comp_info and ae_project_xray at a glance.

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

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

Explicitly says to use it 'to understand an unfamiliar comp before editing' and names both alternatives with their conditions (ae_get_comp_info for one comp's settings/layer list, ae_project_xray for whole-project issues). Routing is fully determined.

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

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

Adds real context beyond annotations: it explains that the 'read' temporarily applies the effect on a temp comp and removes it within the same undo step, which justifies readOnlyHint=false and reassures the agent that comps/layers are untouched. It also documents failure behavior (unknown effect names fail with suggestions). Minor gap: no mention of whether the temporary application can fail on effects requiring specific layer types.

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

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

Three dense sentences, front-loaded with the purpose and payoff, then the side-effect/undo behavior, then the alternate mode. 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 enumerates what is returned (names, match names, value types, defaults, min/max). Side effects, mode selection and error behavior are covered; only edge cases (invalid comp/layer, effects that cannot be instantiated) are 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 baseline is 3; the description adds cross-parameter semantics the schema does not convey, notably that comp+layer must be combined to target an already-applied effect and that omitting them yields a fresh default instance. The effect-name vs. index nuance is left to 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 (List) plus resource (an effect's parameters) with the exact returned fields enumerated in parentheses. It is clearly distinguished from siblings ae_apply_effect, ae_set_effect_params and generic property readers like ae_get_properties.

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

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

Explicitly states the purpose is to obtain exact parameter names for ae_apply_effect / ae_set_effect_params, and gives a clear selection rule between the two modes: default fresh instance vs. pass comp+layer to read an already-applied effect with current values.

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?

Critical context the annotations cannot convey: readOnlyHint=false is surprising for a measuring tool, and the description explains exactly why — it inserts a temporary probe layer and removes it in the same undo step, leaving the user's layers untouched. That resolves the apparent mutation risk and confirms the destructiveHint=false claim in prose.

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 definition, then usage and alternative, then the side-effect disclosure. Every sentence carries information — the toComp reference, the safe-area margins, and the undo behavior all matter to a caller.

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

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

No output schema exists, and the description names the reported categories (bounds, visibility, in-frame status, action-safe and title-safe) which is enough to interpret the result at a high level. It stops short of describing the actual response shape, so an agent still has to inspect the return value to learn field names.

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

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

Schema description coverage is 100%, so every parameter (comp, time, frame, layers, selectedOnly, includeExtents) is already documented in structured data. The description clarifies the semantics of the measurement (post-transform, camera-aware) but adds no per-parameter meaning such as layer-name vs index behavior or default-time resolution.

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 ('Exact on-screen bounding boxes of layers in composition pixels') and pins down the measurement pipeline (after transforms, parenting, 3D and the active camera via toComp()). It is clearly distinguishable from measurement-adjacent siblings like ae_get_layer_info and from the mutation path ae_align_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?

Gives concrete use cases ('check alignment, spacing, overlaps and safe areas with numbers') and explicitly routes the related mutation to ae_align_layers via ae_call. It lacks an explicit when-not clause (e.g., versus ae_get_layer_info or ae_get_comp_map), so it falls just 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds a real behavioral fact: the call fails if the comp or layer isn't found. It does not mention that 'full info' on a heavy layer may be a large payload, nor any cost/size guidance, which keeps it just short of a 5.

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

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

Two sentences, front-loaded with the returned payload followed by the failure condition and the sibling routing. Every clause carries information; nothing is redundant.

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

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

There is no output schema, yet the description compensates by enumerating the returned fields, so an agent knows what to expect. Error behavior and alternatives are also covered, leaving no meaningful gap for a two-parameter read tool.

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

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

Schema coverage is 100% and the schema itself documents the id-or-name duality for both comp and layer, including the 'active' default. The description adds nothing about parameter semantics, 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?

States a specific verb and resource ("Full info for one layer") and then enumerates exactly what is included — switches, timing, parent, source, transforms, effects, masks, markers, text, animated/expression properties. This level of specificity makes it immediately distinguishable from the info-gathering siblings.

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

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

Explicitly routes the agent to three named alternatives with the condition that selects each: ae_get_comp_info for all layers in brief, ae_get_properties for the full property tree, ae_get_layer_bounds for the on-screen box. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds meaningful traits beyond that: the tool is 'quick', the file path is null when the project has never been saved, and it enumerates the return payload since no output schema exists. It does not mention behavior when no project is open, which keeps it from a 5.

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

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

Two sentences, neither padded. The return contents are front-loaded before the routing guidance, so an agent skimming the first clause already knows what it gets back.

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

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

With no output schema, the description carries the burden of describing returns and it does so field by field, plus it routes every adjacent need to the correct sibling. Nothing an agent needs in order to call it correctly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly spends no words on arguments.

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 ('Summary of the open project') and then enumerates exactly what that summary contains: file path, dirty state, item counts, bit depth, render queue size, active item. An agent can tell immediately that this is orientation/overview and not a listing tool like ae_list_comps.

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

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

Gives an explicit ordering instruction ('call it first to orient') and then names four alternatives with their respective domains: ae_status for connection/permission mode, ae_list_comps / ae_list_items for comps and items, ae_project_health for problems, ae_project_xray for how a project works. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations, especially that large trees are truncated and can be narrowed by depth or path, and it lists the kinds of property data returned. A 4 rather than 5 reflects that the exact return shape and any truncation limits are only lightly described.

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

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

The description is front-loaded with the core purpose, then immediately adds routing guidance and truncation behavior. Every sentence earns its place: the field list, read-only note, setter prep guidance, sibling alternatives, and truncation workaround all provide actionable information without 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 six-parameter discovery tool with no output schema, the description is complete enough: it names the returned property fields, explains path/depth usage, warns about truncation, and routes to sibling tools for search and keyframe detail. An agent has what it needs to call this correctly without relying on missing output documentation.

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 six parameters are already documented in the input schema. The description adds some context for path and depth in relation to subgroup inspection and truncation, but it does not meaningfully elaborate keyframes or includeHidden beyond what the schema already states. Baseline 3 is appropriate because the schema is doing most of the parameter-documentation work.

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

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

The description uses a specific verb, 'Inspect', and a precise resource, 'property tree of one layer (or a sub-group via path)', then lists the contents surfaced: names, match names, values, keyframe counts, and expressions. It also distinguishes the tool from ae_find_properties and ae_get_keyframes, so an agent can identify it without opening sibling schemas.

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

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

It gives explicit when-to-use guidance: discover property paths before ae_set_property, ae_set_keyframes, and ae_set_expression. It also names concrete alternatives and the conditions selecting them: ae_find_properties for whole-comp name search and ae_get_keyframes for exact timing/easing. Truncation guidance to lower depth or start at a path is included.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds what the payload actually contains — ES3 rules, helpers, match names — which helps the agent decide whether fetching is worthwhile. It does not state the return format or approximate size, a minor gap for a content-retrieval 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 clauses with zero filler: the first declares the return contents, the second gates usage. The core purpose is front-loaded ahead of the usage caveat.

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 zero-parameter, read-only retrieval tool with no output schema, the description covers what is returned and when to call it. The only missing pieces are the response's form (raw text vs. structured) and rough length, which matter somewhat when deciding to spend context on it.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics for the description to carry. Nothing is missing on this dimension.

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 — 'Returns the After Effects ExtendScript cheat sheet' — and enumerates its contents (ES3 rules, helpers, common match names). It also explicitly distinguishes itself from the dedicated tools, notably ae_run_script, so an agent can separate it from siblings without opening anything.

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 both sides of the decision: use it 'before writing complex ae_run_script code' and it is 'not needed for the dedicated tools.' That names the trigger condition and the exclusion, leaving nothing to infer.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered; the description still adds value by declaring the empty-state semantics (empty lists when nothing is selected, comp null when no comp is active). It leaves the exact return structure undocumented, which with no output schema is a modest gap.

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

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

Two dense sentences, front-loaded with what is returned, then when to reach for it, then the redirect to the mutation sibling. No filler and no repetition of annotation metadata beyond a brief 'Read-only' confirmation.

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-param read tool with no output schema, the description covers scope, empty-state edge cases, and cross-tool compatibility of returned paths. It could go slightly further on what a 'project item' entry contains, but an agent has everything needed to call it and interpret an empty result.

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 there is nothing for the description to disambiguate and the baseline applies. The description correctly spends no words on parameter syntax.

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 exact resource and its three scopes: project items, selected layers in the active comp, and selected properties. It even states that returned property paths are consumable by ae_set_property, which separates it cleanly from siblings like ae_get_properties or ae_get_layer_info.

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 a concrete trigger ("when the user says 'this layer' or 'the selected ones'") and routes the inverse operation elsewhere ("To change the selection use ae_select_layers (via ae_call)"). Both when-to-use and what-not-to-use-it-for are explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations: the exact folders searched, the fact that AE must be running, and what fields each script entry includes. It does not discuss ordering or pagination, but that is a minor omission for a local read-only listing.

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

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

The description is compact and front-loaded: it first defines the list scope, then what each result contains, then the prerequisite, then the alternatives. Every sentence adds actionable 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 read-only listing tool with no output schema, the description explains search locations, returned fields, the AE-running prerequisite, and how to proceed after listing. There are no significant gaps for correct invocation.

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 optional nameContains parameter is already fully documented in the schema. The description does not add filtering semantics beyond the schema, which is acceptable at the baseline when schema coverage is complete.

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

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

The description states a specific verb and resource: list the user's own After Effects scripts, including the concrete search locations (AE Scripts folder, ScriptUI Panels, and configured scriptFolders). It also names the returned fields and distinguishes this discovery tool from ae_run_script_file and ae_run_script.

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

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

It clearly says to use this tool to find scripts, then explicitly routes execution to ae_run_script_file and routes self-written code to ae_run_script. It also gives the prerequisite that After Effects must be running.

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

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

Annotations already declare destructive/open-world/non-idempotent; the description adds substantial beyond-schema behavior: only sampled video frames are compared, alpha is included, audio and comp background color are excluded, and 32 bpc values above 1.0 are clamped. It does not explicitly state that run leaves the project edited (or restores it), which is the key remaining unknown for a destructive tool.

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

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

Front-loaded with the goal, then action-by-action breakdown, then exclusions and limitations – a clean information hierarchy. The limitation parenthetical is dense and the run semantics (whether edits persist) are compressed to the point of ambiguity.

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 12 parameters, the description does the necessary work: it names the return payload (proof id, verdict, per-frame max difference, changed pixels, ΔE, area, difference image) and the sampling limits. The main gap is what happens to the project state after run, which matters given destructiveHint=true.

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 92%, so the baseline is 3; the description still earns credit by tying parameters to actions ('default: active comp, 5 frames over the work area') and by revealing that capture returns a proof id, which the schema cannot express. It doesn't add extra semantics for tolerance, maxSize or atomic beyond what the schema says.

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 goal ('prove a structural change left the render unchanged') and then enumerates the three concrete actions (capture/compare/run) with what each does. It explicitly names the sibling ae_render_frame as the wrong tool for picture-changing edits, so an agent can distinguish it without reading schemas.

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

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

Gives explicit when-to-use ('prove a structural change... or show which frames and areas differ'), when-not-to-use ('Not for edits meant to change the picture (look at those with ae_render_frame)'), and a non-obvious case rule ('For un-precompose, prove the parent comp'). That is a full routing decision tree in three sentences.

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

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

Annotations flag destructiveHint=true and readOnlyHint=false; the description clarifies exactly what that means in practice — a file is written only when outputPath is supplied, and an existing file is never replaced unless overwrite is set. That is genuine added context beyond the annotation. Minor gap: it doesn't say whether rendering perturbs the open composition's playhead/state, which matters for idempotentHint=true.

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

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

Three tight sentences: purpose and output shape first, defaults second, alternative tool and write-safety last. Nothing is wasted or buried.

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

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

For a zero-required-parameter preview tool with full schema coverage and annotations, the description covers output shape, defaults, file-write safety, and sibling routing. Only the interaction between `times` and `frames` (mutually exclusive selection of sampling) is left to the schema, which is a small residual 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 100%, so all nine parameters already carry defaults and constraints. The description restates the frame-count and work-area defaults and the outputPath/overwrite relationship, which is useful reinforcement but adds no semantics the schema lacks.

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 ('render several frames') plus specific output form (one grid image with per-cell time/frame labels), and it explicitly distinguishes itself from ae_render_frame. An agent knows exactly what this produces 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?

Gives the use case ('judge motion, timing and easing, not just a single frame') and names the alternative with the selecting condition ('For one frame in detail use ae_render_frame'). This is explicit when-to-use routing, not 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?

Beyond the annotations, it discloses important behavior: rendering goes through a temporary comp that is removed afterward, hidden layers are restored, large frames are downscaled, and files are written only with outputPath and never replaced unless overwrite is set. These details substantially clarify side effects and lifecycle.

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

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

The description is dense but well structured: purpose first, then inspection options, downscaling, alternatives, and side effects. Every sentence carries operational value, and no space is wasted on restating schema details.

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

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

Given nine parameters, a nested compareWith object, destructive file-write potential, and no output schema, the description covers what the tool returns and the important behavioral caveats. An agent has enough information to invoke it correctly and understand its side effects.

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 parameter documentation is already strong. The description adds useful semantic context for key options: region zooming, layer-only rendering, checkerboard/color transparency, difference-image comparison with black meaning identical, and overwrite refusal behavior.

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

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

The description states a specific verb and resource: render a frame of a composition and return it as an image. It explicitly distinguishes itself from ae_render_contact_sheet for motion and ae_sample_pixels for exact colors, so an agent can select it without inspecting sibling schemas.

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

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

It provides explicit usage guidance: use after visual edits, use ae_render_contact_sheet for motion, and use ae_sample_pixels via ae_call for exact colors. The alternatives and selection conditions are named directly.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description layers on execution semantics the agent could not otherwise know: the script runs as a function body, the whole script is one undo step, errors return with the failing line and surrounding code, log output is returned, and returned AE objects are auto-summarized to JSON. It also names the language limits (no async/await, Promise, Map/Set, generators) and the 1-based collection indexing, which materially affect how code is written.

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 one-line purpose, then bulleted detail with zero filler sentences. The aemcp helper enumeration and the JavaScript feature list are dense but each entry carries actionable information; a slightly tighter presentation could trim a few characters without losing meaning.

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 fully: it describes what comes back (returned value, summarized AE objects, log output, errors with line context) and how deeply objects are serialized. For a 7-parameter, open-world, destructive execution tool, nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: it explains that `code` is a function body using `return`, that `args` is exposed to the script as a variable, and that transpilation exists because of ExtendScript's older JS dialect (with the exact supported/unsupported feature list). `depth` and `report` are left to the schema, which already documents them well.

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

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

States a specific verb (execute) and resource (JavaScript inside After Effects' ExtendScript API) plus the return behavior. It explicitly differentiates itself from siblings by saying dedicated tools are preferable for common edits and that ae_run_script_file handles on-disk scripts, so an agent can place it in the toolset without opening any schema.

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

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

Explicit when-to-use (anything the dedicated tools don't cover) and when-not-to-use (common edits → dedicated tools; script file on disk → ae_run_script_file), plus a pointer to ae_get_scripting_guide for the API cheat sheet. Alternatives and the conditions that select them are named, not 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?

Goes well beyond the annotations (which only say destructive/openWorld/non-idempotent): it discloses that the run is a single undo step, that it returns the last expression's value plus a change report, how args are injected as the AEMCP_ARGS global, and the failure modes (missing file, Read-only mode). That is exactly the behavioral context the annotations cannot convey.

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

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

Front-loaded with the action and the File > Scripts analogy, then the return/undo/error facts in compact clauses. No filler sentences; each one carries a distinct, actionable fact.

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 explaining what comes back (last expression value plus a change report). For a destructive, open-world tool with three params, the safety, return, and failure behavior are all covered.

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 path, args and timeoutSeconds are already documented in the schema, including the AEMCP_ARGS default and the 1–3600 timeout range. The description's mention of args as the AEMCP_ARGS global largely restates the schema rather than adding new syntax or format guidance, 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?

Specific verb+resource: runs an existing .jsx/.jsxbin file from disk inside After Effects, with a concrete analogy (File > Scripts > Run Script File). It explicitly distinguishes itself from the closest sibling, ae_run_script, and points at ae_list_scripts as the discovery path.

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?

States when to use this tool (an existing script file on disk, e.g. one found via ae_list_scripts) and when not to (code you author yourself → ae_run_script). It also names two hard preconditions: a missing file is an error, and the call is refused in Read-only mode.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered; the description adds the return payload (expression, enabled flag, AE error, evaluated value at current time), which matters since there is no output schema. It does not state that an existing expression is overwritten irreversibly or point at ae_undo, which is the main remaining behavioral gap for a destructive write.

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

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

Two sentences, front-loaded with the action and the clear-case before the sibling routing list. The dense parenthetical of four tool names is information-dense rather than wasteful, and no sentence is 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 no-output-schema mutation tool, the description supplies the return fields, the clearing convention and alternatives, which is nearly everything an agent needs. It stops short of noting irreversibility of overwrite or the recovery path via ae_undo, a minor gap given destructiveHint=true.

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%, including the enabled flag and the 'empty string removes the expression' semantics, so the schema carries the parameter burden. The description only restates the empty-string clearing convention and adds the 'one property' scoping; it contributes nothing about path/layer/comp resolution 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 set (set, replace, clear) applied to a specific resource (an expression on one property), and the parenthetical '(empty string)' defines the clear case immediately. It explicitly distinguishes itself from ae_check_expression, ae_replace_in_expressions and ae_get_expressions, so an agent can differentiate without opening other schemas.

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

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

The second sentence gives explicit routing rules: use ae_check_expression to try without keeping, ae_replace_in_expressions for bulk text edits, ae_get_expressions to list. Each alternative comes with the condition that selects it, and it notes all are reached via ae_call.

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

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

Annotations already declare destructive=true and idempotent=true; the description adds valuable semantics beyond them: an existing key at the same time is replaced while other keys survive unless clearExisting, and the tool returns the property's keyframes. It never addresses failure modes (invalid path, locked property) or undo, which keeps it from a 5.

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

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

Front-loaded with purpose, then behavior, then a compact concrete example, then sibling routing — no filler sentences. It is a dense single block of prose, but each clause (replacement semantics, return value, alternatives) 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 6-parameter destructive mutation with no output schema, the description covers selection of time vs frame, replacement/retention semantics, the return value, and routing. The main gap is no guidance on failure conditions or the need for ae_undo after destructive clears, but the core call is fully specified.

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, path, layer, keyframes, ease, interpolation, and clearExisting in detail. The description's example illustrates the keyframe object shape (time/frame, value, easeIn) but adds no syntax or constraints the schema lacks, so 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 opens with a specific verb+resource: 'Create keyframes on a property in one call'. It then distinguishes itself from ae_set_property, ae_edit_keyframes, and ae_set_keyframe_table by naming each and what they do differently, so an agent can route correctly without opening schemas.

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

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

Explicit alternatives with conditions: static value → ae_set_property, editing existing keys → ae_edit_keyframes, exact tables across many properties → ae_set_keyframe_table. It also states the time vs frame placement choice and clearExisting behavior, leaving little to inference.

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

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

Annotations only say write, non-destructive, idempotent; the description adds the important hidden behavior that a keyframe is set implicitly when time is given or the property is already animated, plus that the new property state is returned. It stops short of mentioning side effects such as undo or checkpointing and behavior on expression-driven properties.

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 the keyframe rule, then examples, then alternatives — a sensible order. The examples cluster is dense and slightly repetitive with the path schema examples, but each sentence still carries information needed to call 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?

With five parameters, no output schema, and an annotation profile that covers safety, the definition covers the return value, the failure case, the implicit-keyframe gotcha, and the sibling routing needed to pick the right tool. Nothing an agent needs in order to invoke it correctly 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 3 is the baseline; the description earns more by pairing example paths with example values (path 'Transform/Opacity' value 50; 'Effects/Fill/Color' '#ff0000'), showing accepted value shapes. The time parameter's keyframe-replacement semantics are restated but gain the extra animated-property caveat.

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?

A specific verb plus resource ('Set the value of any property') scoped to transform, effect parameter, shape attribute and text, so the range is unambiguous. Concrete examples (Transform/Opacity, Transform/Position) and explicit sibling routing make it distinguishable from ae_set_keyframes and ae_set_effect_params.

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 states the alternative tools and the condition that selects each: 'For several keyframes with easing use ae_set_keyframes, for expressions ae_set_expression, for many parameters of one effect ae_set_effect_params (via ae_call).' It also names the failure conditions (path is a group or not found), which is clear guidance on when this call will fail.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description focuses on what annotations can't say: it lists every running instance, explains how the session's target is selected, and describes failure behavior (the error states why, e.g. not running or not accepting scripts). Only return formatting/pagination-like detail is absent, which is minor here.

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

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

Four short sentences, each doing distinct work: what it reports, multi-instance handling, when to call it, and where to go instead. The most decision-relevant facts (what it returns, call-first advice) are 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?

With a single optional parameter, no output schema, and annotations covering safety, the description still enumerates the returned fields and explains error behavior and sibling routing. There is no meaningful gap an agent would need filled before calling it.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond the schema by explaining the scenario in which `instance` matters (multiple AE instances open) and that omitting it retains the current target. That situational framing is genuinely additive rather than a restatement.

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 ('check the connection to After Effects') followed by an enumeration of exactly what is reported: version, OS, open project, active item, permission mode, busy state. It explicitly distinguishes itself from ae_get_project_info, which covers a different surface (project contents).

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 entry condition ('Call this first if unsure AE is reachable') and names the alternative for a related need ('For the project's contents use ae_get_project_info'). The multi-instance case is also routed explicitly: pass `instance` to choose the target when several are 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?

Annotations already establish that this is a safe, read-only, idempotent lookup. The description adds useful behavioral context beyond annotations: it can discover unloaded tools, lists them one line per tool by category, and can describe up to 10 chosen tools with full parameters. It does not describe the exact response shape or pagination, but for a discovery tool with strong annotations this is a minor gap.

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

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

The description is front-loaded with the core purpose and usage model, then lists categories that matter because the schema does not provide a formal enum. Every sentence supports discovery, lookup filtering, or execution handoff, 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?

Given a two-parameter read-only discovery tool with no output schema, the description is complete enough to use correctly. It explains both output modes, the category filter, the describe limit, the relationship to ae_call, and the fact that already-loaded tools do not need lookup.

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

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

Schema coverage is 100%, so the schema already documents both optional parameters. The description still adds meaningful semantics by enumerating the category values and clarifying that describe returns full parameter details for up to 10 chosen tools, which goes 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 gives a specific verb and resource: discover/list/describe After Effects tools, including ones not loaded in this chat. It clearly distinguishes discovery from execution by naming ae_call as the way to run a discovered tool, and it distinguishes lookup from direct invocation for already-loaded tools.

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

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

It explicitly states when to use this tool: when a tool is not loaded or when you need its full parameter details. It also states when not to use it: tools already loaded need no lookup and can be called directly, and running a discovered tool should go through ae_call.

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

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

Goes well beyond the annotations: it discloses the undo granularity (one MCP edit call, including an ae_batch, equals one step), the failure behavior when nothing is undone, and the return payload of count plus a cross-comp change report. This is exactly the mutation-and-failure context an agent needs before committing.

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

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

Four tight sentences, front-loaded with what the tool is, followed by granularity, failure mode, and alternatives. No filler and no repetition of 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?

There is no output schema, yet the description states what is returned (steps undone and a change report across all comps) and what happens on failure. Nothing an agent needs to invoke this correctly 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 already documents the 1-50 range and early-stop behavior, so the schema carries the load. The description still adds real meaning by explaining what counts as a single step and that a multi-step undo yields an aggregate change report.

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 ('Undo the last action(s) in After Effects') and anchors it to a familiar UI analog ('Edit > Undo'). It also defines the unit of an undo step, which no sibling tool does, so an agent can distinguish it from ae_checkpoint and ae_redo.

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 routing: use ae_redo to reverse this, restore an ae_checkpoint to go back further, and ae_call to reach ae_redo. It also states the precondition that After Effects must have something undoable and no modal dialog open.

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