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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds the optimism/locking protocol an agent must follow (require expectedVersion, on DECK_CONFLICT re-read and repeat the same intended change) and a cost signal ('Free'). It stops short of saying what existing slide content/arrangement is replaced, which would matter given the destructive hint.

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 usage trigger, then the two modes, then the version/conflict rule, then cost. Phrasing is somewhat compressed and run-on ('Give one slide another composition from its layout (variant 1 to the number the deck result's compositions gives...)'), but every sentence carries information.

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 an 8-parameter mutation tool with no output schema, the description covers the decision between variant and templateId, the required version guard, and the retry path. Missing only the failure modes beyond DECK_CONFLICT and the semantics of the remaining optional parameters.

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 coverage is only 25% (projectId, expectedVersion), so the description carries real weight and does: it scopes variant to 1..N where N comes from the deck result's compositions, and clarifies templateId means a slide from another built-in layout. locale and accountHandle remain unexplained in both schema and 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?

States a specific verb and resource ('arrange one slide differently', 'Give one slide another composition') that plainly distinguishes it from deck-wide siblings like antix_apply_deck_layout or antix_set_deck_palette. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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?

Gives concrete triggers ('user asks to arrange one slide differently, or a review finding suggests another composition') and explains the choice between the two modes: variant from the current layout vs templateId from another built-in layout. It does not mention when to prefer antix_apply_deck_layout or antix_edit_deck_slides instead.

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