Add slide

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's job is to add context, and it does add that layout/theme/notes are applied at creation time. It omits where the slide lands by default (append vs. insertionIndex) and says nothing about the result — no output schema exists, so the agent cannot tell whether a slide ID is returned for follow-up formatting calls.

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?

A single front-loaded sentence with no filler, and the core action leads. It is arguably too terse for an 8-parameter mutation tool, but there is no wasted phrasing to trim.

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 non-destructive mutation with full schema coverage and annotations, the description covers the main capability but leaves two agent-relevant gaps: default insertion position and what the call returns. With no output schema to fall back on, the return value gap matters for chaining into format_text or set_speaker_notes.

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 all 8 parameters including the layout and theme enums are documented in the schema itself. The description restates title/body/bullets/theme/notes at a high level and adds nothing about insertionIndex, presentationId format, or the bullets-overrides-body precedence beyond what the schema already says; 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?

States a specific verb+resource (add a slide) and enumerates what can be filled in on that slide. It distinguishes itself implicitly from element-level siblings like add_text_box or add_image, but never names a sibling or explicitly contrasts with create_deck_from_outline or duplicate_slide.

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?

No statement of when to use this versus the ~20 alternatives, notably create_deck_from_outline (build a whole deck) or duplicate_slide (copy existing content). The reader must infer that this appends one new slide to an existing presentation, and nothing warns that content is placeholders rather than arbitrary shapes.

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