slides_write

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

No annotations are provided, so the description carries the full burden. It does add real traits: slides inherit the deck's layouts/theme, output is "Verified against the saved deck," and delete/duplicate semantics are noted. But it omits destructive warnings for `delete`, permission/auth implications, the 60-slide cap, and any return-value behavior.

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?

Front-loaded with the purpose, then the entry model, then markdown behavior, then the verification note. Dense but no wasted sentences for a tool this complex; the parenthetical at the end is the only mildly disposable line.

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 complex write tool with no annotations and no output schema, the description is reasonably complete on input behavior but silent on what a successful write returns (e.g. resulting slide numbers/ids) and on limits like maxItems 60. An agent knows how to call it but not what to expect back.

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 67% and the per-parameter descriptions are already rich (body markdown grammar, layout names, shapes-by-number, after/insert semantics). The description largely restates this, adding the mode switch (`slide` present vs absent) but little syntax beyond what the schema documents.

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 pair and resource: "Add slides or change existing ones, in the deck's own layouts and theme." The add-vs-modify distinction keyed on presence of `slide` is spelled out. It does not, however, differentiate itself from siblings like slides_edit or slides_replace, which share the same domain.

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?

Strong intra-tool guidance: no `slide` adds a new slide, `slide: N` modifies one, and change operations (skip, move, duplicate, delete) are enumerated. However there is no cross-tool guidance telling the agent when to choose slides_write over slides_edit, slides_replace, or slides_type, which is the harder selection decision.

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