Add Layer To Group

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description adds one useful behavioral fact beyond that: empty group layers are valid targets. It does not disclose what happens to layer ordering, whether the source layer is duplicated or moved, or what happens on name collisions.

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 compact sentence with the core operation front-loaded and no filler. It is not padded, though the terseness is part of why other dimensions are thin.

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 non-idempotent mutation tool with 6 undocumented parameters and a 0% schema coverage, the description omits critical context: the role of aprx_path, the semantics of an empty source_map_name, and how add_position affects the result. Having an output schema excuses return-value explanation, but the input-side gaps remain substantial.

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 there are 6 parameters (4 required), so the schema gives no semantic help. The description covers only three of them conceptually (source layer, target map, group layer) and says nothing about aprx_path, source_map_name (default empty string — presumably meaning same map), or add_position (default AUTO_ARRANGE). This leaves the ambiguity of cross-map moves and placement policy unexplained.

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 clear verb and resource: moving an existing project layer into a target map's group layer. It implicitly distinguishes itself from siblings like arcgis_pro_insert_layer, arcgis_pro_copy_layer, and arcgis_pro_create_group_layer by scope (project layer into an existing group), though it never names an alternative.

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 when-to-use guidance, no prerequisites (must the group layer already exist? must the source layer be in the same project or loaded in a map?), and no mention of the closest siblings such as copy_layer or insert_layer. The agent must infer selection criteria entirely.

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