document.set_slide_notes

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

No annotations, so the description carries the full burden. It does disclose two non-obvious behaviors: the empty-string clearing convention and that changes round-trip through the <p:notesSlides> node on save. It does not state what happens if the slide has no notes slide yet, whether the operation is idempotent, or any error behavior for an out-of-range index.

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?

Three short sentences, front-loaded with the action, no filler. Minor noise: double space after the parenthetical and RST-style double-backtick markup around the XML node name, which is a bit technical for a tool description.

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 simple 2-parameter mutation with no annotations and no output schema, this covers the core action, the clearing case, and persistence behavior. It falls short on the 'index' parameter's exact semantics and on what the tool does when the target slide has no notes slide, which are the two gaps an agent would actually trip over.

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 description coverage is 0% and the description only annotates one parameter partially: 'notes' accepts an empty string to clear. The 'index' parameter is never explained beyond the ambiguous '(default: current)', so an agent cannot tell whether it is a zero-based slide index, a slide ID, or something else.

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 and resource: 'Set or clear the speaker notes on a slide', which clearly distinguishes it from set_text, set_slide_title, and other content-mutating siblings. The parenthetical '(default: current)' is slightly vague about which slide is targeted when index is omitted, but the core purpose is unmistakable.

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?

Explicitly says how to clear notes ('Pass an empty string to clear'), which is real usage guidance for one branch. However, it gives no guidance on when to use this versus set_text or other text-mutating siblings, no prerequisites, and no exclusions.

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