Delete Comment

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

Annotations already signal destructiveHint=true, so the delete behavior is disclosed. The description adds useful context beyond the annotation: it states the comment belongs to a slide, requires 1-based indices, and returns a JSON confirmation. It does not describe error behavior for invalid indices, but the destructive hint lowers the burden.

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 compact, front-loaded with the core action, and uses a clear Args/Returns structure. Every sentence adds useful information, with no filler or repetition of the title.

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 destructive tool with three parameters and no output schema, the description covers the key invocation details, default presentation behavior, required parameters, and return type. It is slightly incomplete in that it does not address invalid-index handling or mention permanence, but the destructiveHint annotation partially covers the latter.

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?

With 0% schema description coverage, the description carries the full burden for parameter meaning, and it does explain all three parameters: presentation, slide_index, and index. It even clarifies base indexing and the source of the index. However, the description marks slide_index and index as required while the schema gives them default null and no required list, creating a potentially confusing discrepancy.

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 opens with a precise verb and resource: 'Delete a comment from a slide.' It is clearly distinct from sibling tools like delete_slide, delete_shape, add_comment, and get_comments because it names the comment as the target object and specifies its location on a slide.

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 procedural guidance: slide_index and index are both required, and index should be obtained from get_comments. It does not explicitly name alternatives or say when not to use the tool, but the 'from get_comments' hint gives an agent a concrete workflow.

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