reorder_layer

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

No annotations are supplied, so the description carries the full behavioral burden and mostly does not. It says 'Returns status dict' without describing success/failure signalling, and it never states whether the move is reversible, whether out-of-range positions are clamped or rejected, or whether the active layer changes as a side effect. For a state-mutating operation on a layer stack, that is a significant 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 purpose is front-loaded in one line, followed by a compact parameter block and a one-line return note. No filler sentences. The bulleted format is easy to scan, though the 'Returns status dict' line adds little and could have been spent on the missing precedence rule.

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?

With no annotations and no output schema, the definition should cover mutation semantics and the return shape, and it only half does. Parameter meaning is adequately covered for a four-parameter tool, but the precedence between the two layer identifiers and the effect of an invalid position are missing. It is minimally sufficient to call the tool, not sufficient to call it confidently.

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% and the schema only supplies titles and defaults, so the description does real work: it defines new_position as a stack index with 0 = bottom, notes layer_name/layer_index default to the active layer, and records image_index's default target. The remaining gap is precedence when both layer_name and layer_index are provided, which is left unstated.

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 first sentence gives a specific verb and resource: 'Move a layer to a new stack position.' That is unambiguous and separates it from transform_layer (geometric change) or set_layer_properties. It stops short of naming a sibling or explaining how reorder differs from a general layer mutation, so it is clear but not sibling-differentiated.

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 statement of when to use this versus alternatives such as transform_layer or set_layer_properties, and no prerequisites (e.g. an open image or an existing layer stack). Nothing warns that the change may need an undo to reverse or that the active layer matters. The agent is left to infer usage entirely from the verb.

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