delete_item_permanently

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

Adds substantial context beyond the annotations: permanently breaks Zotero Word plugin citations silently, version check prevents concurrent edits from being discarded, and idempotency_key behavior with replay and error on key reuse. No contradiction with annotations.

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 detailed but every sentence contributes necessary information for a destructive operation. The structure is clear, with the warning front-loaded and parameter explanations organized into paragraphs.

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?

With no output schema and high complexity, the description covers key behaviors: permanent deletion, citation breakage, version check, and idempotency. It could mention typical return values or error formats, but overall it is sufficiently complete for safe invocation.

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%, but the description explains version (must match current server version, otherwise delete refused) and idempotency_key (unique per request, replay behavior, error on reuse with different args). The key parameter is implied by context but not explicitly described.

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 clearly states the tool permanently deletes an item from its library and notes it cannot be undone. This distinguishes it from siblings like trash_item and restore_from_trash, using a specific verb and resource.

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?

Provides explicit guidance on when to use: only when the consequence of broken citations is accepted, not as routine cleanup. It also explains the version precondition and idempotency key usage for retries, but does not name specific alternative tools.

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