Set Layer Order

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

The description discloses crucial behavioral traits beyond the idempotentHint annotation: it clears any custom draw order, freezes a snapshot list, and causes layers added later to silently draw behind everything. This gives the agent critical side-effect information that cannot be inferred from the schema or 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?

The description is extremely concise—two sentences—yet conveys purpose, parameter semantics, and a critical side-effect warning. Every word adds value; there is no repetition or filler. The structure front-loads the main action and then adds necessary detail.

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 simplicity (one parameter, no output schema, simple annotations), the description covers all essential aspects: what it does, how the parameter works, and an important behavioral caveat. It is complete for an agent to select and invoke this tool correctly without needing additional information.

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 has zero description coverage for layer_ids, but the description fully compensates: it explains that layer_ids is an ordered list from top (drawn last) to bottom, and that unlisted layers keep their slots. This adds vital meaning beyond the raw schema, making the parameter behavior fully explicit.

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 states a specific verb and resource: 'Reorder layer tree nodes.' It further clarifies that tree order equals draw order, which distinguishes it from other layer-related tools like set_layer_property or set_layer_visibility. The purpose is unambiguous and clearly separates it from siblings.

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 when to use the tool: to change the visual stacking of layers. It implies its uniqueness among siblings (no other tool reorders layers), but does not explicitly name alternatives or list when not to use it. The warning about clearing custom draw order serves as an important consideration, effectively guiding usage.

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