deleteDocumentParts

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is known. The description adds genuinely new context beyond that: the exact consequence ("irreversible — data removed or overwritten by this call cannot be recovered through the API") and how dry_run behaves (preview returned as normal text and structured content, not sent to Polarion). It stops short of describing cascade behavior for child parts or permission requirements.

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 irreversible-effect warning and the dry_run tip are front-loaded and earn their place. The closing sentence about the executor returning previews "as structured content when the tool declares an output schema" is meta-commentary that does little work here, since no output schema is declared for this tool.

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 destructive bulk-delete with a nested request body and no output schema, the description covers the two things an agent most needs: irreversibility and a validation path. It omits whether deleting a part cascades to children, how missing/unknown IDs are handled, and required permissions, which are meaningful gaps for a destructive operation but not blocking.

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 100%, so every parameter — including the nested requestBody.data array — is already documented in the schema. The description reinforces that the body is a list of Document Part IDs and contextualizes dry_run, but adds no format, limit, or edge-case detail beyond the schema. Baseline 3 applies.

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 ("Deletes a list of Document Parts") that an agent can clearly separate from getDocumentParts, postDocumentParts, moveDocumentParts, and overwriteDocumentParts. It does not explicitly name which sibling is the non-destructive alternative, so it stops short of full sibling differentiation.

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 gives a useful pre-flight recommendation ("set dry_run: true first to validate the arguments"), which is usage guidance for safe invocation. However, it never says when to choose this tool over overwriteDocumentParts, moveDocumentParts, or deletePage — the destructive-vs-modifying distinction among siblings is left to inference.

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