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

Annotations already flag destructiveHint=true and idempotentHint=false. The description adds real context beyond them: only passed roles change, text re-fits, expectedVersion is mandatory, and DECK_CONFLICT requires re-reading and retrying. It doesn't say whether overwritten text is recoverable or what a success response contains.

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?

Usage triggers are front-loaded and most sentences carry information the schema doesn't. 'Free.' and 'Does not publish.' are terse and valuable, though 'text re-fits its place' is slightly vague and the description is dense enough to reward a second read.

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 destructive 11-parameter mutation with no output schema, the description covers the crucial behavioral contract: versioning, conflict recovery, selective role updates, and non-publishing. It still omits what a successful call returns and leaves several parameters unexplained, so it is strong but not fully complete.

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?

With only 27% schema coverage across 11 parameters, the description carries a heavy burden. It explains the creative roles, emphasis behavior (including empty-string reset), and expectedVersion/conflict handling well, but says nothing about deckId, slideId, locale, projectId, or accountHandle, leaving nearly half the parameters undocumented in both places.

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 uses a specific verb ('Replace the words'), scopes it to one slide, and enumerates the exact roles (headline, body, kicker, cta) plus emphasis. The example utterances make the intent unmistakable, but it never explicitly names a sibling like antix_edit_deck_slides to draw the boundary.

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?

It opens with explicit trigger phrases ('rewrite slide 3', 'make the headline shorter', 'change the call to action') and adds a boundary ('Does not publish'). It lacks an explicit statement of when to use a different tool, so it falls short of a 5.

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