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?

Beyond the destructiveHint annotation, the description discloses key behaviors: arguments are validated before reaching AE, every call is wrapped in one undo group, and the response includes ambient context at zero extra round trips. It also warns against calling beginUndoGroup/endUndoGroup in eval.run code. This adds substantial context beyond the structured annotation.

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?

Though the description is longer than average, every sentence conveys essential information: purpose, usage guidance, undo behavior, response context, and example. It is well-structured and front-loaded with the core purpose, then expands into usage details without 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?

Given the tool's generic nature (executes any catalog operation) and lack of output schema, the description covers invocation, validation, batching, undo behavior, response contents, and includes an example. It is sufficiently complete for an agent to select and invoke the tool correctly, especially with sibling tool 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 schema already documents all three parameters with 100% coverage. The description adds value by explaining validation semantics ('Arguments are validated against the operation's declared parameters'), clarifying that args can be omitted for zero-param operations, and providing a concrete example with operation and args. This goes beyond what the schema alone provides.

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's function: 'Execute an atomic operation by name (from ae_catalog).' It distinguishes ae_do from sibling tools like ae_comp_info and ae_layer_info by positioning it as the generic executor for operations defined in the catalog, making the purpose specific and unambiguous.

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

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

Provides explicit usage guidance: 'Have more than one operation to run? Wrap them in ONE batch.run instead of several ae_do calls' and notes that read/verify steps can ride in the same batch. It also clearly states when not to use ae_do (for undo/redo operations that cannot ride inside 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?

Beyond the readOnlyHint annotation, the description states that the tool reads bundled local workflows and does not open After Effects or use the network. This gives the agent useful expectations about side effects and runtime behavior. It does not cover error cases, but for a simple local read operation that 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 compact and front-loaded: first the operation, then the parameter modes, then the practical recommendation. Every sentence adds information without repeating the schema or title.

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

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

For a simple read-only retrieval tool with no required parameters, the description covers core behavior, parameter combinations, and recommended starting point. There is no output schema, so a slightly more explicit statement about what the index/entry contains would be nice, but the description is already sufficient 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?

The schema already documents each parameter, so the baseline is 3. The description adds meaningful higher-level semantics: omitting name returns the index, supplying name returns an entry, and supplying reference targets a specific listed module. This is exactly the kind of usage nuance the schema alone does not convey.

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

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

The description opens with a specific verb and object: 'Read bundled local AE workflows.' This clearly identifies a read-only retrieval tool, distinguishing it from sibling tools like ae_save_project or ae_do that perform actions. It also explains the index-versus-entry behavior, making the purpose fully unambiguous.

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

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

The description explains when to call the tool ('Start with ae-clean-rig before building or editing projects') and how to select retrieval scope by omitting or supplying parameters. It stops short of naming alternative sibling tools or contrasting when another tool would be better, but the usage context is clear enough for an agent.

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?

Beyond the single destructiveHint annotation, the description discloses headless and deterministic execution, the transient OCIO color transform behavior, fallback paths, and the colorWarning/colorPipeline response fields to inspect. This is substantial behavioral transparency.

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 purpose and usage, then provides necessary technical caveats about color management. Every sentence earns its place; there is no filler or empty marketing language.

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 sparse annotations, this description is unusually complete. It explains the output format, color-managed behavior, fallback scenarios, and which response fields to check, while parameters are already fully documented in 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?

Schema description coverage is 100% with detailed parameter documentation. The description reinforces color behavior but does not add meaningful parameter-level meaning beyond what the schema already provides, so the baseline 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 states a specific verb and resource: 'Render a single frame to PNG.' It goes further by framing the tool as the agent's 'eyes' for visually verifying edits, which clearly differentiates it from the sibling project-management and automation 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 says to use the tool to visually verify edits and recommends pairing it with mutations for a visual feedback loop. It does not name exclusions or alternative tools, but the intended usage context 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?

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.