Run DeckCraft engine commands

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

Annotations already declare destructive=true, readOnly=false and idempotent=false, so the safety profile is covered. The description goes further by disclosing execution semantics (steps run in order, stop-on-first-error by default), the live-vs-headless switch, and the save step. It does not restate the destructive/overwrite implications, but the added batch and mode context is substantive.

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 core behavior is front-loaded ('Advanced: run any DeckCraft engine commands in order'), followed by the command families, the step-reference rule, coordinate units, and the live flag — each contributing real information. The long single-paragraph enumeration of command families is dense, but none of it is 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?

For a 14-parameter batch executor with a nested steps array and no output schema, the description covers the essential mental model: what steps are, how to reference prior results, how coordinates work, and the live/headless distinction. It does not describe the return payload or save/overwrite outcome in detail, which is the main remaining gap given the absent output schema.

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 only 57%, so the burden to compensate is real, and the description does add non-schema semantics that are critical to correct use: step ids map to tool names, parameters can reference prior results via '$steps[N].field', and coordinates are in points (16:9 = 960x540). It still leaves several parameters (name, formats, output_dir, preview_slides) unexplained, but the mechanism-level additions are valuable.

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 gives a specific verb and resource ('run any DeckCraft engine commands in order') and enumerates the command families and engine tools it accepts, so an agent knows exactly what this does. It is clearly a batch/advanced executor on a new or opened presentation. However it never explicitly contrasts itself with edit_presentation or create_presentation, so sibling differentiation is left to inference.

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 'Advanced:' marker and 'on a new or an opened presentation, then save' give implicit context for when to reach for this tool rather than the simpler siblings. But it never states when NOT to use it or names edit_presentation/create_presentation as the alternatives for single edits. Usage is implied rather than spelled out.

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