Auto-Fix Slide from Canva Comment / Feedback

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write/open-world profile is known. The description adds real context beyond that: it explicitly says the tool 'tự động ghi đè' (automatically overwrites) the revision into the Slide Engine and optionally writes a PNG thumbnail, which tells the agent changes are destructive and unconfirmed. It still omits permissions/auth needs, failure behavior, and whether the overwrite is reversible.

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?

It is a single dense sentence with no filler or repetition, so nothing is wasted. However, the long comma-separated parenthetical of edit types makes it hard to parse at a glance, and the destructive overwrite — the most important fact — is buried mid-sentence rather than front-loaded.

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 tool with 6 parameters (all optional, all defaulted) and no output schema, the description covers intent and the overwrite/thumbnail side effects, which is the core need. It does not say what the tool returns on success, what happens when the comment cannot be parsed into an edit, or what the defaults (design_id DAHaKPDSZSI, slide 16, a hardcoded local .pptx path) imply about side effects.

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 100%, so every one of the 6 parameters is already documented in the schema; baseline 3 applies. The description adds no syntax or format detail for design_id, slide_number, presentation_path, or export_thumbnail beyond restating the comment_id/comment_text either-or that the schema already 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?

The description names a specific verb chain (analyze comment -> extract edit intent -> overwrite slide) and the resource (Canva comment / Slide Engine), and enumerates the concrete edit classes it handles (font >= 24pt, metrics, palette, badge, layout). It is clear what the tool does, but it never names a sibling, so an agent cannot tell from this text alone why it should prefer this over canva_read_design_comments + canva_validate_slide_copy + canva_export_slide_thumbnail.

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 when-to-use / when-not-to-use guidance at the tool level; the only conditional logic stated ('if comment_id is not passed, use comment_text') is an input-selection rule, not a routing rule. Nothing says whether to read comments first with canva_read_design_comments, or whether this should be run only after canva_validate_slide_copy.

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