insert_slide

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

The annotations only mark readOnlyHint=false, yet the description discloses atomic saving, two-slot backup rotation, the backup=False opt-out, and the three live= modes with their locked-file behavior and UNSAVED caveat. This is substantial behavioral context well beyond the structured annotation.

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 dense and runs several clauses together, but each clause earns its place and the core action is front-loaded. A bit more separation of parameter definitions would improve readability without adding length.

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?

Given the tool's complexity—layout selection, positional insertion, backup semantics, and live PowerPoint-lock handling—the description covers all essential behaviors and references the relevant discovery/list commands. With an output schema present, not detailing return values is acceptable.

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 0%, so the description must add parameter meaning, and it does: layout is disambiguated by name/index and how to list them, position is defined as 0-based final index with end default, backup is tied to rotation behavior, and live receives explicit auto/force/off semantics. Only file_path is left to obvious inference.

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?

Description opens with a specific verb and object ('Add a slide built from a layout') and distinguishes the operation from sibling slide tools like delete_slide, duplicate_slide, and reorder_slides. It also states the key mechanism (placeholder skeleton inheritance) so the agent understands what this insertion accomplishes beyond a generic add.

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 clearly positions this as the tool for adding a slide to an existing deck and points to list_elements kind='layouts' for discovering valid layout identifiers. It names create_presentation as the alternative for whole-deck creation, which is an explicit boundary, though it doesn't spell out exclusions for sibling slide-editing tools because those are implied by their names.

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