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

Annotations only declare non-read-only, non-destructive, non-open-world, so the description carries real weight and does: it states content and figures are preserved, numbers are verified against the source, the brand is applied, and that generation is asynchronous (2-4 minutes) returning a deal_id immediately, with downloads via the web app. That is exactly the behavioral context an agent needs before calling a long-running mutation.

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?

The action and input are front-loaded, then the pipeline and async follow-up, which is the right order. The parenthetical list of deck types ('coursework, a lecture, a report, a pitch') is padding that could be cut without loss.

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?

With no output schema, the description must explain returns and it does: a deal_id immediately, then a shareable link and PowerPoint/PDF downloads via the web app. Combined with the async timing and the sibling handoff to get_rebuild_status, an agent has everything needed to invoke and complete the workflow.

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 100%, so the baseline is 3; the description earns above that by adding extraction semantics the schema does not — pull title and body from the user's uploaded file, one entry per slide, in order. The mode parameter's preserve-vs-condense tradeoff is left entirely to the schema, which limits it to a 4.

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 opens with a specific verb set (improve, redesign, polish, rebrand) applied to a precise resource: an existing presentation, explicitly distinguished from creating a new one. It also names the accepted source formats (PowerPoint, Google Slides, Keynote), so the agent knows exactly which request this tool owns.

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 tells the agent what to pass (the text of every slide, in order) and spells out the follow-up step: this call returns a deal_id and get_rebuild_status must be called for the link. The only gap is that the sibling create_deck is never named as the alternative for new decks — the split is implied by 'existing' rather than stated.

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