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

Annotations only declare readOnlyHint=true, and the description adds real value on top: it discloses the return shape per mode (categories with counts vs. params per operation) and the important scoping constraint that only operations this server will execute are listed. It does not cover item limits or pagination behavior, keeping it 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?

Four tight sentences, front-loaded with purpose and then the argument-driven modes. The final sentence about executable-only operations earns its place as a meaningful constraint; nothing is redundant 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?

With no output schema, the description carries the burden of describing returns and does so adequately for each mode (categories and names; params detail; schema-only fetch). Nothing an agent needs to select and invoke this tool 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 description coverage is 100% and each parameter's constraints (enum for detail, maxLength, maxItems 12) are already documented in the schema. The description's mention of combinations is largely a restatement of those same descriptions, so it earns the baseline rather than exceeding it.

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

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

States a specific verb and resource (discover atomic operations for ae_do) and immediately clarifies how behavior changes based on arguments. An agent can distinguish this discovery tool from the ae_do executor sibling 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 clear conditional guidance for each mode: no args for the category overview, a category for detailed params, detail: summary for browsing, operations: [...] for targeted schema fetches. It stops short of explicitly saying 'call this before ae_do to learn valid operation names,' so the routing to the sibling is implied rather than stated.

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

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

Annotations declare readOnlyHint, so safety is covered. The description adds meaningful behavioral context by listing the exact comp properties returned and noting that an array fetches several comps in one call, which tells the agent what to expect beyond annotations.

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

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

Two tightly packed sentences with zero filler. The key capabilities (returned fields, batching) are front-loaded and easy to scan.

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

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

For a read-only info tool with no output schema, the description adequately enumerates the returned data and batching behavior. It could mention error cases or use of the instance parameter, but the schema already covers instance 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 coverage is 100%, so baseline is 3. The description adds a semantic nuance: passing an array fetches several comps in one call, clarifying batching behavior beyond the schema's type definition.

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: 'Detailed comp info' and enumerates the returned properties (size, fps, duration, work area, motion blur, layer summaries). It does not explicitly name sibling tools to differentiate, so not 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?

No explicit when-to-use, when-not-to-use, or alternative-tool guidance. The description only covers parameter input (name/ID or array). The schema mentions calling ae_project_info first, but that context is absent from the description itself.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description adds useful behavior beyond that: the compact-vs-full default and what the full mode unlocks (item list, helpers, ES3 rules, tips, undo contract). It stops short of describing output shape, but with annotations carrying the safety profile this is solid added context.

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

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

Three sentences, zero waste, front-loaded with the returned contents before the usage directive. 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?

With no output schema, the description does the work of telling the agent what comes back in both modes and when to call. It is nearly complete for a read-only context tool; only the resident/instance addressing details live purely in the schema, which is acceptable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by enumerating what detail:'full' actually returns (helpers, ES3 rules, tips, undo contract), giving semantic weight the enum values alone don't 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?

States a specific resource set (project state, active comp, selected layers, resident readiness), which clearly separates it from siblings like ae_project_info or ae_comp_info. The verb 'ambient context' is slightly abstract but the enumerated contents make the purpose concrete.

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 'Call at session start; then rely on ae_do response context,' giving clear when-to-use and a routing rule to the follow-up sibling. No explicit when-not condition, but the sequencing guidance is unambiguous.

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

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

Annotations only carry destructiveHint=true, and the description goes well beyond that: automatic undo-group wrapping (one Ctrl+Z reverts the whole call), a warning never to call beginUndoGroup/endUndoGroup in eval.run, argument validation happening before AE is contacted, and the undo/redo exception. This is exactly the behavioral context the annotation 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 core verb and the most common mistake (multiple ae_do calls), then rule, exception, and example. Dense but every sentence carries a rule or constraint. Slightly long, but nothing 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?

No output schema exists, and the description compensates by noting the response includes ambient comp/selection/project context at zero extra round trips, plus undo semantics and validation timing. For a mutation tool whose only annotation is destructiveHint, this is complete enough to call safely.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds an end-to-end example showing how operation and args nest (keyframe.add with comp/layer/property/time/value), which clarifies arg shape beyond the schema. It does not add much on instance, timeoutMs, or includeContext, so it lands above baseline but not at 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+resource: 'Execute an atomic operation by name (from ae_catalog)', and explicitly ties the operation namespace to the ae_catalog sibling. An agent can distinguish it from ae_edit, ae_workflow, and ae_do's own batch pattern 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?

Explicit guidance on when to use it: single atomic operations, vs wrapping multiple in one batch.run, with named read/verify steps (comp.info, layer.info, render.frame) that can ride along. It also names the exception (undo/redo: project.undo, command.execute id 16/2035) that must not go in a batch.run.

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 declare destructiveHint=true, so the description carries most of the burden and delivers: idempotency via UUID requestId ('prevents repeat execution after a retry or timeout') and the exact side-effect pipeline (captures pre-edit values, saves a checkpoint, edits, reads back, saves the project). Missing only auth/permission requirements and what the checkpoint can be rolled back to, which keeps it off 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?

Four sentences, each carrying distinct payload: capability, idempotency, execution pipeline, and status/scope exclusion. The operation and its limits are front-loaded before the recovery path and the negative scope statement.

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

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

For a destructive, no-output-schema mutation tool, the description covers atomicity, retry safety, checkpointing, and where to fetch a delayed result, plus the instance-addressing parameter is documented in the schema. It omits failure/error semantics and whether the checkpoint is restorable, which is the main remaining gap.

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

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

Top-level schema description coverage is 100% and the nested operation enum is self-documenting, so the baseline is 3. The description still adds genuine meaning the schema does not: the requestId is framed as a deduplication/retry-safety key rather than just a uuid format, and it confirms the 12-edit ceiling as a hard constraint.

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 ('apply') and resource ('up to 12 typed, registered edits to the active managed .aep copy') with a clear scope limit. It also explicitly separates itself from sibling rendering tools with 'This does not render frames,' so an agent can distinguish it from ae_render_frame 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 a concrete follow-up path ('Use action=status with the same requestId to inspect a delayed receipt') and an explicit exclusion ('This does not render frames'). It stops short of routing the agent between this tool and the semantically adjacent ae_do / ae_workflow, so the when-to-use-vs-alternative coverage is clear 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?

readOnlyHint=true already declares the safety profile, yet the description still adds real behavioral detail: the 16-target cap, the shape of the return (values, key counts, reusable opaque references), and the caveat that repeated sibling match names cannot yield reusable property references.

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

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

Four dense sentences, each carrying distinct information — capability, return shape, prerequisites, and an edge-case limitation — with no filler or repetition.

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

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

No output schema exists, so the description appropriately summarizes the return payload. With only three params and 67% coverage, prerequisites and limits are covered; only the instance-selection semantics of the nested target objects are left to the schema.

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

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

With 67% schema coverage, the description still adds meaning beyond the schema: it clarifies that layer indices are 1-based (the schema only says exclusiveMinimum 0, which is ambiguous), that property paths use canonical match names, and that compId is a composition (not item) ID. It does not explain the nested propertyPath index field.

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 ('Inspect ... layer or property targets in one read') and quantifies scope ('up to 16'), which distinguishes it from per-object siblings like ae_layer_info and from the general-purpose ae_do.

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 input prerequisites (numeric composition ID, 1-based layer indices, canonical match names) but never says when to prefer this batch inspector over ae_layer_info, ae_comp_info, or ae_do. Usage is implied by the 'one read' batching framing rather than stated.

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

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

Annotations only declare readOnlyHint=true, so the description carries extra weight and delivers: it warns the full tree is often 100KB+ per comp and that includeProperties=false skips the property walk entirely. This is actionable performance/cost context beyond the structured fields. It does not cover auth or instance-resolution behavior, which the schema fields handle instead.

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 dense sentences, front-loaded with the returned content and then the scoping/size guidance; each clause carries information. Slightly long, but nothing is 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?

No output schema exists, and the description compensates by enumerating the returned structure, the size expectation, and the detail/includeProperties downgrades. Combined with 100% parameter coverage, an agent has enough to call it correctly; only the instance-resolution nuance and no explicit sibling routing leave minor gaps.

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

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

Schema description coverage is 100% and every parameter is already documented in the schema, so the baseline is 3. The description's layerIndex sentence largely restates the schema's anyOf (single index, array, 'all'), though it adds the audit rationale for batching. It adds little semantic detail 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?

States a specific verb+resource with an explicit enumeration of what is returned (transform, effects, masks, text, shape contents, keyframes with interpolation names). It is clearly distinguishable from siblings like ae_comp_info or ae_project_info. An agent can tell exactly what this call yields 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 real usage direction: use detail:'summary' to start audits, and 'all' to audit a whole comp in one round trip. It explains the flag trade-offs but never names or excludes a sibling tool, so it stops short of full alternative routing.

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

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

readOnlyHint=true already marks this as safe, but the description adds real context: it is offline, never contacts AE, never applies edits, and the audit phase deliberately proposes nothing. Those constraints are not derivable from the annotation alone. It does not disclose return shape, but with no output schema that is a moderate gap rather than a contradiction.

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 carrying information: purpose, phase flow, non-mutation guarantee, and the readback prerequisite. The 'Supply real readback and render before/after' prerequisite is front-loaded enough, though it is terse and could be clearer about what input field it refers to.

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

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

For a single-parameter, deeply nested planner with no output schema, the definition covers the essential contract: it plans, it does not execute, and it requires verified AE measurements because it cannot inspect comps. Missing only a hint about what the returned plan/ops look like, which is minor given the tool's clearly bounded scope.

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 nested spec object is self-documenting, so the baseline is 3. The description adds meaning by mapping intent onto the 'phase' field (prepare / reveal / audit) and by flagging that frame values must come from live AE readback, which the schema also reinforces — useful but largely redundant with structured data.

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 ('Offline motion planner') and scopes it to the concrete asset types (typography, panels, icons, bars). It also implicitly separates itself from the mutating ae_* siblings by saying it never contacts After Effects, though it never names ae_workflow_plan or ae_edit directly.

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 phase sequence ('Prepare pivots, reread positions, then request reveal ops') and the note that the audit phase 'checks camera samples without proposing edits' imply when each mode applies. It stops short of naming alternatives or stating when NOT to use the tool for planning versus asking ae_workflow_plan/ae_edit.

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 only destructiveHint=false in annotations, the description carries most of the burden and does well: it discloses the disk-write side effect, that inline output may be large, and the full scope of what is serialized. It stops short of noting performance cost on large projects or any error behavior, keeping it below a 5.

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

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

Two tightly written sentences with zero filler. The scope enumeration leads, and the output-destination rule follows immediately, making it fully 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, but the description compensates by enumerating the exact JSON contents (comps, layers, keyframes, effects, etc.) and flagging that inline responses can be large. Combined with a fully documented parameter schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and all three parameters (pretty, outPath, instance) have thorough descriptions, so the schema does the heavy lifting. The description's mention of outPath vs inline is a restatement of what the schema already documents, adding no format or syntax detail beyond it — the 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 (serialize/export) and resource (entire project) and enumerates exactly what is captured — folders, comps, layers, keyframes, effects, shapes, markers, time remap, solids, file refs. This clearly distinguishes it from the inverse sibling ae_project_import_json and from ae_save_project, which persists rather than serializes.

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

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

Explains the mode selection rule — set `outPath` to write to disk, omit it to get the JSON inline — which is the key decision an agent must make. It does not, however, say when to prefer this over siblings like ae_project_info (summary) or ae_save_project (persist), so routing among related tools 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?

Annotations already declare destructiveHint=true, and the schema fully documents clearFirst's destructive behavior and skipValidation's risk. The description's recitation of parameter names adds no behavioral context beyond the structured data, and says nothing about auth, instance defaults, or failure semantics.

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

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

Front-loads the core action and provenance in one clause, then lists flags tersely. Slightly fragmentary ('Supports ...'), but nothing wasted.

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

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

For a six-parameter mutation tool with no output schema, the description plus the fully-covered schema and the destructiveHint annotation cover what an agent needs to invoke it. It stops short of describing return/plan output or rollback behavior after a destructive clearFirst import.

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 (including the mutually-exclusive json/inPath pair and the instance addressing) are already fully documented in the schema. The description only restates three flag names, adding no meaning beyond 'dryRun (validate-only)' which the schema itself 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+resource ('Rebuild the project from JSON') and explicitly identifies the producing sibling (ae_project_export_json), which no sibling tool list otherwise resolves. An agent can tell this is the inverse of the export tool.

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

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

The pairing with ae_project_export_json implies when to reach for this (round-tripping an export), and 'dryRun (validate-only)' hints at a pre-flight use. But there is no explicit when-not or guidance on choosing between inline `json` vs `inPath`, leaving usage 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?

readOnlyHint=true already covers the safety profile, and the description adds real behavioral value by disclosing the return payload (dirty flag, item list with type/summary, active item) even though no output schema exists. It does not cover the multi-instance addressing behavior, but that is documented in the schema.

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

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

A single compact sentence listing the payload, followed by a two-word directive. No filler, and the enumerable content is front-loaded before the 'Start here' call to action.

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-param, read-only info tool with no output schema, describing the returned fields is the key completeness requirement and it is met. The only gap is clarifying its position relative to the comp/layer info siblings, which 'Start here' only loosely implies.

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?

Only one optional parameter and schema description coverage is 100%, so the detailed `instance` semantics live entirely in the schema. The description adds nothing about instance selection, which is acceptable at the baseline given full schema coverage.

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 (project) and enumerates exactly what is returned: file path, dirty flag, items with type/summary, active item. This distinguishes it implicitly from ae_comp_info and ae_layer_info, which are the comp- and layer-level counterparts, though it never names those siblings 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?

'Start here.' gives an implied entry-point hint, telling the agent this is a reasonable first call before drilling into comps/layers. There is no explicit when-not-to-use or named alternative, so guidance remains inferred rather than stated.

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

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

With only destructiveHint=false in annotations, the description carries the behavioral load and does well: it discloses that preview can dirty the project, that AE may ignore the resolution request (check previewWarning), the file naming scheme, the OCIO display-transform mechanism, and the fallback ladder to ACES/raw with colorWarning. It does not cover auth/permissions or instance contention in depth, but the mutation-risk and failure-mode disclosure is notably strong.

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 before the mode-specific detail, and each sentence covers a distinct concern (motion, contact sheet, analysis, color). It is dense and long for one tool, with some overlapping statements about warnings, but little is pure 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, yet the description names the return surface the agent must read (frames, analysis, colorPipeline, colorWarning, previewWarning) and explains the color-managed fallback chain. For a 10-param tool with nested objects and no output schema, this is complete enough to call and interpret 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 baseline is 3, but the description adds real meaning beyond the schema: it specifies the <outPath stem>_<index>.png landing convention, that frames are index-aligned in `frames`, and that analyze acts on the capture before color conversion. Those are semantic relationships not encoded in the property descriptions.

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?

Opens with a specific verb+resource+output format ('Render one or more frames to PNG') and immediately frames the role ('the agent's eyes ... pair with mutations'), which cleanly separates it from planning/save/inspect siblings. An agent knows exactly what this produces versus ae_comp_info or ae_do.

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 ('Use to visually verify edits'), a clear routing rule for time vs times, and prescriptive guidance for each mode: contactSheet for one-image motion checks, analyze for numeric off-frame detection, full resolution for fine-detail approval, and preview only as an experimental path. Alternatives and exclusions (preview can dirty the project) are stated, not inferred.

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

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

Annotations already declare destructiveHint=true, so overwrite risk is flagged structurally, but the description adds no behavioral context of its own (no overwrite warning, no undo/irreversibility note, no permission requirements). With annotations carrying the safety profile, the description contributes essentially nothing beyond restating the name.

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 filler, with the Save As affordance front-loaded. Nothing wasted.

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

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

For a simple two-parameter save tool with 100% schema coverage and a destructiveHint annotation, the definition is largely complete; the only real gap is that overwrite/irreversibility context is left entirely to the annotation rather than being reinforced in text.

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

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

Schema description coverage is 100% and the `path` description already explains the Save As behavior and the never-saved error. The description merely repeats a subset ('Pass `path` for Save As') without adding format or constraint detail, 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?

States a specific verb and resource ('Save the project') and distinguishes the Save As variant via the `path` argument. Clear enough for an agent, though there is no need for sibling differentiation since no other tool in the list saves.

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 line 'Pass `path` for Save As' implies when to supply the argument, but the description itself gives no when-not guidance or note about the failure case; that context lives only in the schema's parameter 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?

The readOnlyHint annotation already establishes this is a safe read. Beyond that, the description discloses what the response reports (capability availability), which is decision-relevant for an agent choosing which APIs to attempt. It does not cover instance-resolution failure behavior, but the annotation carries the safety burden.

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

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

Two compact sentences: the first declares exactly what comes back, the second declares when to call it. No filler, no restatement of the title, and the highest-value information leads.

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

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

With no output schema, the description does the work of sketching the return payload (version, build, capability list), which is sufficient for a trivially simple zero-required-param info tool. Only minor detail, such as the shape of the capability list, 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?

There is a single optional 'instance' parameter and schema coverage is 100%, so the schema already documents instance resolution thoroughly. The description adds nothing about parameters, so the baseline 3 applies.

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

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

The description names the exact resource contents (AE version, build, capability flags like saveFrameToPng, app.effects, Socket), which is far more specific than a tautology on 'Version info'. It implicitly distinguishes itself from info siblings such as ae_project_info or ae_comp_info by scoping to the host application itself rather than a document, though it never names those siblings 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?

'Call at session start to know what APIs are available' gives an explicit trigger condition, which is exactly the kind of when-to-call guidance most descriptions lack. There is no when-not or named alternative, so it stops short of a 5.

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

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

With destructiveHint=true already declared, the description still adds value: apply edits only the copy (not the source project), the job is "guarded" and persisted, and no production render fires automatically. That materially reframes what the destructive flag means 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, front-loaded with the prepare action and ending with the safety note. Each sentence carries a distinct fact; little is wasted.

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

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

For a tool with no output schema and a complex oneOf request, the description covers all three actions, the copy-only constraint, and the no-render guarantee. What a job contains or returns is left implicit, but the agent has enough to choose and 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 description coverage is 100%, so the schema already documents copyPath, jobId, and instance. The description names the two recipe kinds and the action flow but adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States specific verbs and resources: prepare a typed retime or text/logo variants recipe against a managed .aep copy, then apply or read status. The action split is clear from both description and schema. It does not differentiate itself from the sibling ae_workflow_plan, which is the only gap.

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?

"Apply only after reviewing the job, or read its status" plus the schema note "Use prepare first, then apply or status with its jobId" gives an explicit sequencing rule. It stops short of naming when to pick this over ae_workflow_plan or ae_edit, but the workflow ordering is genuinely actionable.

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 give readOnlyHint=true, and the description reinforces this by explicitly stating it never contacts AE and never applies edits—useful non-contradictory confirmation. It also discloses the contract: validates whole-frame timing and returns typed operations plus a readback plan. It stops short of describing failure behavior on invalid input.

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 no filler. The core identity (offline recipe) is front-loaded, followed by the return contract and the safety boundary.

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

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

With no output schema, the description usefully summarizes the return ('typed operations plus a readback plan') and coverage of the nested spec is complete via the schema. Minor gaps remain around what an invalid plan response looks like.

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

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

Schema description coverage is 100% and the single nested 'spec' object is heavily documented in-schema (fresh live readback, whole comp frames, 1–16 tracks). The description adds only light framing ('whole-frame timing', 'one AE batch'), so baseline 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?

States a specific verb+resource ('Offline recipe for retiming several inspected property tracks in one AE batch') and distinguishes itself from execution siblings by asserting it 'never contacts After Effects or applies edits.' An agent can immediately tell this apart from ae_do or ae_motion_plan.

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?

Clearly frames the context: batch retiming of already-inspected tracks, produced as an offline plan before execution. It does not name a specific alternative tool (e.g., ae_do for applying the plan), so the routing is implied rather than explicit.

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