Set layer properties

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

The annotations already provide readOnly=false, destructive=false, and idempotent=true; the description adds a valuable behavioral guarantee beyond those flags: only the supplied fields are modified, so unspecified properties are not reset. This is especially useful for a 14-parameter mutation tool. There is no contradiction with the 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 sentences with no filler, front-loaded with the action and target resource. The property list is compact but informative, and the crucial 'only given fields change' clause is placed clearly at the end.

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 complex 14-parameter setter with no output schema, the description covers the core function and patch semantics, and the annotations address safety and idempotence. But it omits some parameters (active, sampling), does not describe return behavior, and leaves failure semantics to inference. The description is adequate but not complete enough for a complex setter.

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 only 43%, so the description needed to compensate for the many parameters lacking schema-level explanations. Instead, it largely restates parameter names in categories without clarifying semantics for terms like sampling, active, or the exact flip behavior. The partial-update statement is the only real added semantic value.

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 a specific verb and resource ('Changes... of a layer') and enumerates the property families it covers: name, visibility, opacity, blend mode, mask enablement, and transform. This scope implicitly distinguishes it from siblings like set_layer_mask, replace_layer_image, and move_layer. The sentence 'Only the given fields change' adds precision about the mutation semantics.

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 property enumeration implies when to use the tool: when you need to modify any of these layer attributes in a targeted way. However, it does not explicitly route around siblings such as set_layer_mask, move_layer, or replace_layer_image, nor does it state when not to use it. The usage context is inferred rather than stated.

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