ae_manageItems

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

The description advertises 'delete', 'remove unused', and 'consolidate' — operations that remove project content — while the annotations declare destructiveHint=false. That is a direct conflict with what the annotation promises a harness or agent. The description also adds nothing about id resolution (item name vs index vs id), undo/irreversibility, or failure 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?

A single front-loaded sentence with zero filler; the resource scope comes first and the operation set follows. It is compressed to the point of ambiguity ('consolidate/reduce/remove unused') but nothing is wasted.

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

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

This is a 9-action mutation tool with 6 undocumented parameters and no output schema, and the description covers none of the per-action contract: what each action expects, what it returns, or what happens on a bad item reference. For a multi-mode tool, the definition is too thin to call correctly on first try.

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 0%, so the description carries the burden; it partially compensates because its wording hints at the optional params (rename→newName, move to folder→folder, relink→path, set label→label). It never states which parameter each action requires, nor how 'item' (string or number) is resolved, so the mapping still requires trial and 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?

Opens with a specific resource scope ('project item ops') and enumerates the concrete operations (rename, move, delete, relink, label, createFolder, consolidate/reduce/removeUnused) that map one-to-one onto the action enum. It implicitly separates item-level work from the many layer/comp siblings (ae_deleteLayer, ae_precompose), though it never names a sibling explicitly.

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

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

There is no guidance on when to pick this tool over ae_deleteLayer or ae_importFile, no prerequisites (item identification, project must be open), and no ordering or caution notes despite several irreversible-looking actions. The only usage signal is the action list itself, which is implied rather than explained.

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