zotero_create_annotation

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

With no annotations, the description fully discloses behavioral traits: it requires PyMuPDF and a writable library, fails on scanned/image-only PDFs, uses a normalized coordinate system with origin at top-left, and restricts EPUB to highlights. It also notes the error case of providing both or neither text and rect, and explains the exact matching behavior for text.

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?

Despite its length, every sentence adds essential information. The structure is logical: purpose and mode constraint first, then detailed parameter semantics, then requirements, then examples. No fluff or redundancy; the density is justified by the tool's complexity.

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?

The description covers all parameters, error conditions, prerequisites, coordinate system, EPUB limitations, and provides examples. An output schema exists, so the absence of return-value details is acceptable. The description is complete for an agent to correctly select and invoke this tool.

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 0%, so the description must compensate fully. It does: attachment_key is clarified as the attachment key not the parent item, page is 1-indexed (chapter for EPUB), text must match the text layer exactly, rect is a normalized [x,y,width,height] array with origin and fitting constraints, and optional params (comment, color, tags) are listed with defaults. Examples illustrate parameter usage.

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 the verb 'Create' and resource 'annotation on a PDF attachment', clarifies EPUB limitation (highlights only), and distinguishes from siblings like zotero_update_annotation and zotero_delete_annotation. The two modes (text vs rect) are clearly defined, making the purpose 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 explains the exactly-one-mode rule and the error condition of passing both or neither. Directs users to call zotero_get_page_layout first for accurate rect coordinates, and specifies prerequisites (PyMuPDF, writable library). It also differentiates usage from related tools by describing when to use each mode.

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