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

Beyond the annotations it discloses a quota ('Up to 20 edits a day'), cost ('Uses no credits'), and asynchronous behavior ('Returns the new slides when the render finishes within about 40 seconds, otherwise a job_id for get_generation'). The one gap is that destructiveHint=true is never explained — nothing says the existing rendered slides are replaced or whether an edit can be reverted.

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 description is front-loaded with what changes, immediately followed by routing guidance, then limits/return behavior. Every clause carries distinct information — no restatement of the title and no filler.

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 takes on the burden and does it: it explains the sync success return versus the job_id fallback and names the follow-up tools (get_generation, get_library_item). Rate limit, cost, and partial-update semantics ('unchanged fields stay as they are') round out what an agent needs to call this safely.

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 parameter including the nested slide fields already carries its own description and examples. The description only restates the field list at a high level and adds no format, constraints, or interaction rules beyond what the schema provides, so the baseline 3 applies.

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 and resource ('Changes the text on slides of a carousel draft') and enumerates the editable surface: headline, subheadline, body, CTA, caption, visual style, plus the re-render side effect. It is clearly separable from generate_content (creates new) and update_draft (text-only drafts).

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 states when to use it and when not to with named alternatives: 'Use it to fix a carousel instead of generating a new one; for text drafts use update_draft.' The agent does not have to open any schema to route between these three tools.

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