adobe_edit_layers

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds genuinely new context by signalling optimistic concurrency ('expected names') and copy scoping, but it never explains what happens on a name mismatch, whether the 64-edit batch is atomic, or whether partial edits are applied before failure.

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 the mutating verbs first and the scoping condition last; nothing is padded. Density is high enough that some terms ('exact paths with expected names') are underexplained, which keeps it from a 5.

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?

The tool is a destructive batch mutation over a nested edit list with an output schema, yet the description omits prerequisite session/copy setup, mismatch failure behavior, and batch atomicity. For a destructive multi-edit operation, these omissions leave an agent unable to predict outcomes on error.

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 0%, so the description must carry parameter meaning. It maps loosely to three nested fields (name for rename, visible for hide/show, opacity) but leaves path, expected_name, session_id, and the application enum completely unexplained, and mentions none of the cardinality limits.

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 specific operations (rename, hide/show, opacity) on a specific resource (layers addressed by path) and scopes the target to an owned copy, which distinguishes it from sibling creation tools like adobe_add_group. It falls short of a 5 because 'exact paths with expected names' is opaque phrasing that only becomes meaningful once the schema is read.

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 phrase 'in an owned copy' implies a precondition (work on an open copy rather than the original), but the description never states that adobe_open_copy must run first, nor does it contrast with siblings such as adobe_add_group or adobe_inspect. Usage is inferable rather than stated, and no when-not guidance is offered.

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