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

The description explains the tool's behavior beyond the read-only annotation: it lists categories vs. detailed params, and highlights that only executable operations are listed, setting accurate expectations. The readOnlyHint=true annotation aligns with the description's non-mutating purpose; no contradiction exists, and the description adds useful context about the two output modes.

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

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

The description is two sentences long and front-loaded with the primary purpose. Both sentences earn their place: the first states what the tool does, and the second details the two invocation modes and the guarantee about listed operations. No wasted words.

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 catalog tool with one optional parameter, read-only annotation, and no output schema, the description provides sufficient context: it explains the return content (categories or params) and the filtering guarantee. Minor omission is that it doesn't explicitly mention operation counts, but the schema's parameter description covers that, making it complete enough.

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

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

The input schema already provides a 100%-coverage description for the single parameter, including behavior when omitted. The tool description reinforces and expands on this by clarifying the exact difference between no-args and with-category outputs, adding value beyond 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?

The description clearly identifies the tool as a discovery mechanism for atomic operations available to ae_do, with a specific verb ('Discover') and a defined resource (available atomic operations). It distinguishes itself from sibling tools like ae_do (which executes operations) and other project/layer tools that serve different purposes.

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

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

The description explicitly explains usage without args (list all categories) and with a category (detailed params per operation), giving clear context for both modes. It also states that only operations the server will execute are listed, which is a key guideline for filtering. It does not name specific alternatives, but the distinction from ae_do is implicit in the wording.

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 no contradiction. The description adds behavioral context by stating the tool returns detailed fields and supports batching multiple comps in one call, which is useful beyond the annotation's safety signal.

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, well-structured sentence that front-loads the key information (what it returns) and then explains the input options. Zero fluff, every word earns its place.

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

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

For a simple read-only info tool with one parameter and no output schema, the description covers all essential details: return content, input flexibility, and batching. No critical information 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 fully explains the nameOrId parameter (string/number/array, exact match, fallback to ae_project_info). The description's mention of arrays reinforces but does not add new semantic meaning beyond the schema.

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

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

The description uses a specific verb ('fetch' implied) and resource ('comp info'), lists concrete fields (size, fps, duration, work area, motion blur, layer summaries), and clearly distinguishes from siblings like ae_layer_info (layers) and ae_project_info (project-level) by focusing on compositions.

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

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

The description implies when to use it (when you have a comp name or id) and the schema explicitly advises calling ae_project_info if you lack one. This gives clear context and a specific alternative, though the main description doesn't contrast with other sibling tools.

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

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

Beyond the readOnlyHint annotation, the description discloses the undo contract ('every call = one auto undo group'), which is a notable behavioral trait. It also mentions ES3 rules and AE.* helpers, adding context beyond the annotation. No 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?

Two sentences with high density: the first lists the tool's contents, the second gives the usage instruction. Every word earns its place, no redundancy.

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

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

For a zero-parameter, no-output-schema context tool, the description covers what it provides, when to call it, and how to proceed with ae_do responses. The undo contract mention prevents surprises, making it sufficiently complete for its simplicity.

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

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

There are zero parameters, so the description correctly does not need to explain parameter details. Baseline 4 applies, and the description adds value by clarifying what contextual information the tool returns.

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

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

The description clearly identifies the tool as providing ambient session context, listing specific content like project state, active comp, selected layers, and AE.* helpers. This distinguishes it from sibling tools like ae_comp_info or ae_layer_info, which are focused queries.

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 instructs 'Call at session start' and suggests relying on ae_do response context afterward, giving clear timing and handoff. It does not mention when-not-to-use or list alternatives, but the session-start directive is strong.

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

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

The description itself is unusually forthcoming about side effects (a 'save changes?' question is cancelled, never answered for the user) and about platform/auth requirements (Accessibility permission on macOS for reading text and dismissing). However, that disclosure directly conflicts with the readOnlyHint=true annotation for the dismiss mode: closing a modal dialog changes application state, so an agent trusting the annotation may assume no side effects. Credit for the auth/permission detail is offset by this inconsistency.

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?

Information is front-loaded: verb+resource first, then dismiss semantics, then when-to-use, then platform caveat. Every clause earns its place, though the heavy parenthetical nesting makes it denser than ideal for scanning.

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 still conveys that listing reports open dialogs and that dismiss requires an id sourced from a prior list or error. It stops short of describing the returned dialog fields (text, id shape) or what happens if the id is stale/an unknown dialog, 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?

Schema coverage is 100%, so the baseline is 3 — both `id` and `action` are already documented in the schema, including the list/dismiss enum. The description adds genuine meaning beyond the schema by spelling out what `dismiss` does behaviourally (cancel-equivalent, Escape semantics) and where `id` comes from (a previous list or a DIALOG_OPEN error).

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 both concrete operations — listing currently-shown modal dialogs and dismissing one via its cancel action — with a specific resource (After Effects modal dialogs) that no sibling tool touches. An agent can distinguish this from ae_do, ae_save_project, or any info tool 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?

It gives explicit triggering conditions: use after a DIALOG_OPEN / TIMEOUT error, or proactively before a step known to pop a dialog. It also states what the dismiss mode semantically means (Escape behaviour) so the agent knows which of the two modes maps to its situation.

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; the description goes far beyond by disclosing auto-validation against declared params before AE is contacted, automatic single-undo-group wrapping (one Ctrl+Z reverts the whole call, batch.run counts as one call), the undo/redo exception, and that ambient context (active comp, selected layers, project state) is returned at zero extra round trips.

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 core rules (name source, batching, undo grouping, undo/redo exception) are front-loaded and every sentence carries a distinct constraint. It is dense rather than bloated, though the trailing ambient-context and example clauses pile on after the essential guidance is already delivered.

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 dispatch tool with nested args, a required operation name, and no output schema, the description covers the naming source, validation behavior, batching model, undo semantics, the undo/redo carve-out, and a full call example. Nothing needed 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 description coverage is 100% and each param (args, dryRun, operation, timeoutMs) is already documented in the schema, so the baseline is 3. The description adds a concrete worked example showing the operation/args shape, which is a modest but real value-add over the structured 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 states a specific verb+resource ('execute an atomic operation by name') and immediately anchors it to the sibling that supplies valid names ('from ae_catalog'), so an agent can tell it apart from the purpose-built siblings like ae_comp_info or ae_render_frame.

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

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

It gives explicit routing rules: multiple operations belong in ONE batch.run, read/verify steps (comp.info, layer.info, render.frame) can ride in the same batch, and undo/redo (project.undo, command.execute 16/2035) must run outside the group and cannot ride in a batch. It also issues a clear prohibition ('Never call app.beginUndoGroup/endUndoGroup in eval.run code').

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

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

Annotations declare readOnlyHint=true, and the description adds behavioral nuance beyond that: the batch round-trip efficiency ('auditing a whole comp is one call') and the optional 'property tree walk' that can be skipped via includeProperties=false. No contradictions with annotations.

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

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

Two tightly packed sentences. The primary purpose and content list are front-loaded, followed by the most impactful usage note (batch indices) and the optional flag. Zero filler.

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

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

For a read-only layer inspection tool with no output schema, the description adequately lists the return content categories and explains the includeProperties control. It does not describe the exact return structure, but given the schema's clarity and the read-only annotation, this is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the layerIndex array/'all' behavior already in the schema and adds the property tree walk context, but this is more behavioral than parameter-specific. It does not add meaning beyond what the schema already documents for each parameter.

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 ('Full layer info') with a clear resource (layer) and enumerates the content areas (transform, effects, masks, text, shape contents, keyframes). It naturally differentiates from sibling tools like ae_comp_info and ae_project_info, which target different resources.

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

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

The description gives concrete usage context: layerIndex accepts a single index, an array, or 'all', enabling whole-comp auditing in one call. It also explains the includeProperties toggle. However, it does not explicitly name alternatives or state when not to use it; the sibling distinction is implied but not stated.

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

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

Annotations only provide destructiveHint=false. The description adds valuable behavioral context: it writes to outPath or returns inline, and warns that inline JSON can get large. This goes beyond the minimal annotation and helps the agent anticipate size-related performance implications, though it does not disclose every edge case (e.g., overwrite behavior or exact JSON structure).

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

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

The description is two sentences, front-loaded with the core action and scope, followed by the output-mode detail. Every phrase earns its place; the list of serialized components is concise but informative, and there is no fluff.

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 there is no output schema, the description does the work of explaining what the tool returns by listing serialized components and stating that JSON is returned inline when outPath is omitted. It also flags the potential for large outputs. It could specify the root JSON structure or error behavior, but for a complex export tool, this is a reasonably complete picture.

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% with detailed descriptions for both `pretty` and `outPath`. The tool description simply restates the outPath behavior ('Write to outPath or return inline') without adding new parameter semantics. Since the schema already explains defaults and behavior, the description adds no extra value, meeting the baseline for high 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 clearly states the tool serializes the entire project to JSON with a specific list of included elements (folders, comps, layers, keyframes, effects, shapes, markers, time remap, solids, file refs). This is a specific verb+resource that distinguishes it from siblings like ae_project_info or ae_project_import_json.

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

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

The description clearly implies when to use this tool (for full project export) and explains the two output modes (write to path or inline). It does not explicitly name alternatives or state when not to use it, but the 'entire project' scope and inline warning provide sufficient contextual guidance relative to sibling tools.

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

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

Annotations already provide destructiveHint: true, lowering the burden. The description adds the configurable flags (clearFirst, dryRun, skipValidation) but uses the word 'Rebuild' without clarifying that the default behavior is to append rather than replace. This is misleading and violates the expectation of transparency about side effects.

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

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

The description is a single concise sentence with no filler. It front-loads the primary action and then lists the key optional switches, making it easy to parse.

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?

Although the schema and annotations fill in many details, the description's ambiguous use of 'Rebuild' conflicts with the schema's note that clearFirst defaults to false (appends). This mismatch leaves a critical gap for a mutation tool, as an agent might assume it replaces the project when it actually appends unless told otherwise.

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

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

The schema description coverage is 100%, with each parameter already fully explained. The tool description only names three flags without adding any new semantic information beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Rebuild the project from JSON') and ties it to a sibling tool (ae_project_export_json), making it unmistakable as the import counterpart. This distinguishes it from the other sibling tools and provides a specific verb and resource.

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 context is clear: it is the inverse of ae_project_export_json and should be used when reconstructing a project from an exported JSON file. However, it does not explicitly state when not to use it or mention alternatives beyond the export tool, so it falls 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds what data is returned but doesn't disclose potential behavior such as response size, performance implications, or whether all items are loaded at once, which is minimal for a simple read tool.

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

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

The description is a single, front-loaded sentence that directly states what the tool provides and includes a useful 'Start here' guidance. Every word earns its place with no redundancy.

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

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

For a zero-parameter tool with no output schema, the description fully covers its return values (file path, dirty flag, items, active item) and positions it within the tool family. The 'Start here' hint provides sufficient context for an initial exploration 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?

With zero parameters, there is no schema detail to clarify. The description effectively lists the output contents, compensating for the absence of parameters and adding semantic meaning to the tool's purpose.

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

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

The description clearly states the tool provides project-level info including specific data fields (file path, dirty flag, all items, active item), distinguishing it from sibling tools like ae_comp_info and ae_layer_info which focus on compositions and layers. The phrase 'Start here' reinforces its role as an entry point.

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' implies this should be the first tool used when exploring a project, but it doesn't explicitly state when to use this vs alternatives like ae_comp_info or ae_catalog. No exclusions or alternative recommendations are given.

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

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

Annotations only declare destructiveHint=false, so the description carries the behavioral load and does so richly: headless, deterministic, and a detailed account of the color-management path (OCIO display transform, ACES fallback, raw-values fallback with explicit colorWarning). It even tells the agent to inspect colorPipeline/colorWarning on the response.

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 purpose in the first sentence, then layers the color-management caveats. It is longer than a typical description but most sentences earn their place given the non-obvious color fallback semantics; the dense final sentence is justified by real behavior variance.

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-param tool with no output schema and only a single annotation, the description covers the important hidden behavior (headless determinism, color fallback, response fields to inspect). The absence of an output schema is offset by naming colorPipeline/colorWarning, though exact return shape is left implicit.

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

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

Schema description coverage is 100%, so each parameter already documents its own meaning (time, outPath, compareWith, colorManaged, compNameOrId, useDisplayStartTime). The description explains the color pipeline behavior behind colorManaged='auto' vs 'off' but adds no syntax or format detail beyond the schema. 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 (render a single frame to PNG) and immediately scopes intent: 'Use to visually verify edits. The agent's eyes.' This clearly differentiates it from the many info/do/catalog siblings in the toolset.

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 when-to-use context (pair with mutations for a visual feedback loop, verify edits) but does not name explicit alternatives or when-not-to-use conditions. The context is strong for a specialized tool whose siblings are largely non-overlapping, but it stops short of an explicit routing rule.

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

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

The description adds valuable behavioral context beyond the destructiveHint annotation, such as the error condition for unsaved projects and the Save As path behavior. It does not contradict the annotation and clarifies the tool's side effects adequately.

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

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

The description is two concise sentences, front-loaded with the core action and a precise pointer to the path parameter. Every word earns its place with no redundancy.

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

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

For a simple save operation with one optional parameter, full schema coverage, and a destructive annotation, the description plus schema provide complete guidance. No output schema is needed for a save action, and the behavior is fully documented.

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 description fully explains the path parameter, including Save As semantics and error behavior. The description adds no new meaning beyond a concise restatement, so 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?

The description clearly states the tool saves the project, with a specific verb and resource. It distinguishes itself from siblings like export/import JSON by focusing on native project save, including the Save As nuance via 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?

The schema description provides clear guidance on when to omit path (existing save) versus provide path (Save As), including the error condition if never saved. However, it does not explicitly mention alternatives or when not to use this tool, keeping it just shy 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?

The readOnlyHint annotation already indicates safety, and the description adds that it reports capabilities like saveFrameToPng, app.effects, and Socket. This is useful but minimal; it doesn't detail the response format or potential variations.

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

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

One sentence packs the core purpose and a usage directive, with no filler. The description is front-loaded and every word earns its place.

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

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

For a zero-parameter read-only tool, the description sufficiently covers what the tool returns (version, build, capabilities) and when to use it. No output schema exists, but the description provides enough context.

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

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

The tool has zero parameters, and the schema covers 100% trivially. The description doesn't need to elaborate, so the baseline of 4 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 clearly states that the tool retrieves AE version, build, and capabilities, which distinguishes it from sibling info tools that target specific project/comp/layer resources.

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

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

The description explicitly instructs calling at session start to discover available APIs, providing clear timing guidance. It doesn't name alternatives, but no sibling serves this exact purpose, so the guidance is sufficient.

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