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

Annotations only cover the safety profile (non-readonly, open-world, non-idempotent, non-destructive). The description goes well beyond them: billing rules ('bills per rendered slide', assemble/fork are free), the blocking/retry contract via can_autofix/patch/patch_target, partial-render semantics ('slides that failed ... are free and named in repair_actions'), and the polling identity 'deck_id == job_id'. It even flags a non-obvious gotcha: theme_id does NOT re-theme assembled slides.

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?

Purpose and the slides contract are front-loaded, and most sentences carry non-obvious information. The mid-description fragment 'BLOCKED (not billed)?' followed by conditional error-handling instructions interrupts the flow and reads like a header pasted into prose, which costs it a point.

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 17-parameter tool with nested objects, no output schema, and a billing/polling lifecycle, the description still covers the essentials: mode selection, inheritance rules, the dry_run validation contract, cost implications, error repair, and key return fields (pptx_url, repair_actions). An agent has enough to call it correctly and interpret the result.

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 already 88%, so the baseline is 3, but the description adds real meaning beyond the schema: deck-level vs slide-level precedence ('a slide-level imagery wins'), the exception that covers/dividers on an uploaded template keep the template's own direction, and the fact that force_render and allow_partial are ignored at deck level. It does not, however, explain name vs title or the structure of strict_policy beyond the schema's own text.

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?

Opens with a specific verb+resource+scope: 'Create a complete PowerPoint presentation (.pptx): a whole multi-slide deck, native and editable, in one call.' It explicitly positions slides as 'create_slide intents', which cleanly separates this tool from the single-slide sibling create_slide and from edit_deck.

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?

Names the three modes and when each applies ('mode=assemble merges existing slide job_ids', 'mode=fork clones a deck'), plus the pre-flight workflow ('put dry_run here, not on individual slides') and the error-recovery path for blocked calls. It also routes agents to browse_catalog(type=schema) for new forms and to create_slide for per-slide detail.

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