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

Annotations already establish this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real context beyond them: duplication preserves canonical GMS validity and uses optimistic concurrency via expectedSpecVersion. It does not disclose what is copied (style, filters, visibility) or how failures/stale version errors surface.

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 tight sentences with the core action front-loaded and the version precondition immediately after. No padding or repetition.

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 nested-input mutation with no output schema and three required parameters, the description covers the action and the version guard but omits what the duplicated layer inherits and what the response contains. Adequate but with clear gaps an agent would want filled.

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 low: title and layerId are described in the nested schema, but projectId and expectedSpecVersion are not. The description usefully explains that expectedSpecVersion guards against stale writes, adding meaning the schema lacks. However, it leaves projectId and the relationship between title and the duplicate's name undescribed.

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: duplicate a map layer. That makes its difference from siblings like project_add_layer or project_update_layer_style evident, but it does not explicitly state how it relates to those siblings. The purpose is clear, but it lacks sibling differentiation.

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 offers no guidance on when to duplicate a layer versus using project_add_layer or project_update_layer_style. It only notes that expectedSpecVersion is required to prevent stale writes, which is precondition guidance rather than usage routing.

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