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, and the description adds value by disclosing batch capability ('fetch several comps in one call'), exact-match behavior ('Composition name (exact match)' in schema), and the specific fields returned. It goes beyond the simple read-only annotation without contradicting it.

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 a clear summary and then an invocation note. It is concise, with no wasted words, and the list of fields is efficient.

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

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

There is no output schema, so the description's enumeration of returned fields (size, fps, duration, work area, motion blur, layer summaries) provides essential context. It also covers input modes and batch behavior. It lacks detail on response format for layer summaries, but the description is sufficiently complete for a read-only info tool with a simple input parameter.

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, including accepted types and the array batch option. The main description also mentions 'Pass a comp name or item id — or an ARRAY of them' but adds no new syntax or format details beyond what the schema already provides. Baseline 3 is appropriate here.

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 purpose: 'Detailed comp info' with specific fields (size, fps, duration, work area, motion blur, layer summaries). The verb 'fetch' is implied and the resource (composition) is unambiguous. It distinguishes itself from siblings like ae_layer_info and ae_project_info.

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

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

The main description implies usage for retrieving comp details and mentions batching via arrays. The schema description adds explicit guidance: 'If you don't know any, call ae_project_info first.' This names an alternative tool but does not fully describe when not to use it, though it covers the primary decision point.

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?

The description goes beyond the readOnlyHint annotation by detailing what data is returned and how the includeProperties flag affects the traversal. It also discloses the batching behavior for multiple layers, giving agents a clear picture of the call's scope and performance traits.

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 exceptionally compact—two sentences that front-load the tool's purpose and then provide actionable parameter guidance. Every phrase earns its place without redundant specification.

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 read-only nature and the absence of an output schema, the description sufficiently explains what information is returned and how to request bulk or partial data. It leaves no major gaps for a tool of this complexity.

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

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

While the schema already covers all three parameters with descriptions, the tool description enriches the layerIndex semantics by emphasizing the single-call batching and the includeProperties rationale ('skip the property tree walk'). This adds practical meaning beyond the raw schema definitions.

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 with 'Full layer info' and a specific list of contents (transform, effects, masks, text, shape contents, keyframes). This distinguishes it from sibling tools like ae_comp_info and ae_project_info by explicitly targeting layers.

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

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

The description provides clear context for use, highlighting the ability to pass multiple indices or 'all' for auditing a whole comp in one call. However, it does not explicitly mention when not to use this tool or name alternatives among the listed siblings, so it stops short of a full exclusionary guide.

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 provide destructiveHint: false, while the description goes far beyond that, detailing headless deterministic rendering, color-managed transforms via OCIO, fallback paths to ACES or raw values, and the response's colorPipeline/colorWarning indicators. This gives deep behavioral insight.

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?

Opens with a clear purpose statement, then a usage note, followed by essential technical details. Every sentence contributes substance—there's no filler or repetition. The structure moves from simple to complex, 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?

For a rendering tool with no output schema, the description fully covers what the tool does, when to use it, how it behaves (including color management), what the output looks like (sRGB-tagged vs raw), and what to look for on the response (colorWarning). It also addresses edge cases like read-only mode and missing OCIO effect.

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 thorough parameter descriptions (100% coverage), so the baseline is 3. The description adds extra semantic context by explaining the color-managed behavior in detail, particularly for the colorManaged parameter, and mentioning the effect of working space, which enriches understanding 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?

Clearly states 'Render a single frame to PNG' with a specific verb, resource, and output format. It also frames its purpose as 'the agent's eyes' for visual verification, distinguishing it from sibling tools like ae_project_info or ae_save_project.

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 instructs 'Use to visually verify edits' and recommends pairing with mutations for a visual feedback loop, providing strong contextual guidance. It doesn't explicitly list alternatives or exclusions, but the use case 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.