Set layer states

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

Annotations flag destructive=true and idempotent=true, but the description adds real behavioral context beyond them: items execute in order within a single undo step, the Archicad layer cannot be hidden/locked and is skipped for wildcard patterns, and the per-item return shape (changed/changedCount/alreadyInStateCount/skipped) is documented.

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?

Front-loaded with the core action, then constraints, then an example, then the return shape. Dense and mostly every-clause-earns-its-place, though the parenthetical about saved combinations is slightly packed together with the sibling routing.

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 no-output-schema mutation tool, the description supplies the ordering/undo semantics, the edge-case exclusions, the return shape, and a working example. An agent has everything needed to invoke it correctly.

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 already documents the nested item fields (layer/match/hidden/locked/visible/wireframe/intersectionGroup), so much of the semantics is structured. The description still adds value by showing how match and visible/hidden combine in the isolate example, but doesn't explain the accepted 'layer' forms (index/name/guid) that the schema covers.

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?

States a specific verb+resource (set layer states: show/hide, lock/unlock, wireframe, intersection group) and explicitly scopes it to 'active layer settings'. It distinguishes itself from siblings by naming modify_attributes type LayerCombination as the tool for saved combinations.

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?

Explicitly says when NOT to use it ('saved combinations are not changed — use modify_attributes type LayerCombination for those') and provides a concrete 'isolate' recipe using [{match:'*', hidden:true}, {layer:'Стены', visible:true}]. Routing to the alternative is unambiguous.

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