insert_slide

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

With no annotations, the description carries the full burden and reveals atomic saves, two-slot backup rotation, live-session editing modes, and the critical caveat that live edits remain unsaved until live_save. It also explains layout placeholder inheritance. This is far more transparent than a bare mutation statement.

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?

Four dense sentences are front-loaded with the core add operation followed by parameter-specific behavior. There is no filler; each clause communicates a distinct fact needed to call the tool correctly.

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?

The tool has five parameters, no annotations, and a complex save/live-editing model, yet the description covers layout resolution, placement, backup behavior, locked-file modes, and persistence caveats. An output schema exists, so return-value details are not required. Minor gaps such as exact error handling and live='auto' behavior on unlocked files remain, but nothing blocks a correct call.

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?

The schema has zero descriptions, yet the description explains layout by name or 0-based index and how to list layouts, defines position as the 0-based final index defaulting to end, and clarifies live/backup behaviors. Every non-obvious parameter is covered; file_path is the only one left to inference and is self-evident.

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 opening phrase 'Add a slide built from a layout' names a specific action and resource, and the rest clarifies layout selection by name/index and placeholder inheritance. This differentiates insert_slide from siblings like delete_slide or duplicate_slide, which operate on existing slides.

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?

The description provides clear operational context: layouts can be enumerated with list_elements, whole decks start via create_presentation, and live modes govern locked-file situations. It does not explicitly exclude alternatives such as duplicate_slide for cloning an existing slide, so exclusions are implied rather than fully stated.

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