edit_shape_paragraphs

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

With no annotations provided, the description carries the disclosure burden and does it well: it explains the server-side export/modify/reimport mechanism, that data never enters the model's context, and the key side effect that reimport deletes and reinserts the slide causing PowerPoint to jump to slide one. That side-effect warning is exactly the kind of non-obvious behavior an agent needs before mutating.

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 core action, followed by prerequisites, mechanism, and the caveat with its alternative. Dense and mostly earning its space, though the export/reimport explanation and the view-jump note partially overlap and could be tightened.

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 mutation tool with no annotations and no output schema, the description supplies the full picture: prerequisite read step, required /pptx knowledge, side effects, and the preferred alternative for text-only edits. An agent has everything needed to invoke it correctly and avoid the pitfall.

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 100%, so the baseline is 3; the description adds value by clarifying that xml is the <a:p> paragraph XML that replaces the current text body while bodyPr and lstStyle survive, and by situating shapeId/slideIndex in the read-then-write workflow. It doesn't add format-level detail beyond that, so it stops short of a 5.

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 (replace a shape's paragraph content with raw <a:p> OOXML) and specifies the exact scope of what is and isn't touched (preserves <a:bodyPr> and <a:lstStyle>). It is clearly distinguishable from read_shape_paragraphs and edit_slide_xml without opening a schema.

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 routes the agent: call read_shape_paragraphs first to get current XML, then write it back, and use execute_officejs instead for text-only changes because view position is preserved. Both the when and the when-not are stated with the condition that selects each.

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