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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds two genuinely useful behavioral facts not covered by annotations: Studio supplies defaults/Studio-owned fields, and expectedSpecVersion exists as an optimistic-concurrency guard against stale writes. It does not say what happens on a version conflict, whether the layer is appended or inserted, or what is returned.

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 tightly written sentences with zero filler. The core action is front-loaded and the concurrency constraint follows immediately, so an agent gets the essential facts in one pass.

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 mutation against a very deep nested layer schema, the description is thin: no output schema exists, so the agent gets no hint about the response, and no routing guidance toward the project-level add/duplicate siblings. The rich inline layer documentation in the schema offsets this somewhat, but the description itself does not round out the picture.

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?

Top-level schema coverage is 0%: projectId and expectedSpecVersion carry no schema descriptions, so the description must compensate. It explains why expectedSpecVersion is required, which is the least self-evident parameter, but adds nothing for projectId, and the enormous layer-shape documentation lives entirely in the nested schema rather than the description.

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 ('Add a map layer') and qualifies the scope with 'using Studio defaults and Studio-owned fields', which hints at the distinction from geobble_project_add_layer. It stops short of naming that sibling, so the differentiation is only inferable rather than explicit.

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 tool versus geobble_project_add_layer, geobble_project_duplicate_layer, or other layer-manipulation siblings. The only usage-like guidance is the concurrency requirement ('expectedSpecVersion is required to prevent stale writes'), which is about correctness rather than tool selection.

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