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

Annotations flag destructiveHint=true and idempotentHint=false, and the description earns its keep by disclosing exactly what is destroyed (layout, slide compositions, text styling) versus preserved (every slide's words, and colours/typefaces when keepTheme:true). It additionally states the version precondition, the conflict-retry protocol, and that the call is free.

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?

Information is front-loaded: trigger phrasings, then the operation, then prerequisites and failure handling. It is a single dense block with no wasted sentence, though the trigger-phrase enumeration and the 'Free' remark could be trimmed marginally.

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 destructive mutation with no output schema, the description covers the full operator loop: how to pick a target layout, what gets replaced, how to avoid a stale-version failure, and how to recover from one. The only unused parameter (projectId) is already documented in the schema.

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 only 25% (projectId and expectedVersion only), so the description must compensate; it explains templateId's lib- prefix convention, the meaning of keepTheme, and that look is an alternative styling axis with its own shape. deckId, locale and accountHandle remain undocumented anywhere, which keeps this from a 5.

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?

"Re-lay the whole deck in another built-in layout ... keeping every slide's words" gives a specific verb, an explicit scope (whole deck, not one slide) and a preservation guarantee. The deck-wide scope implicitly separates it from antix_set_slide_layout and, combined with keepTheme, from antix_set_deck_palette/antix_set_deck_fonts.

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?

Supplies concrete user phrasings that should trigger it ('try a different layout', 'use the highlighter layout'), a mandatory prerequisite ('List the layouts with antix_list_carousel_templates first'), and the alternative path (templateId vs look). It also prescribes recovery behavior on DECK_CONFLICT rather than leaving the agent to guess.

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