zotero_create_annotation

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

No annotations are provided, so description carries the full burden. It discloses important behaviors: scanned/image-only PDFs will not match, requires a writable library (web API key or hybrid mode), requires PyMuPDF extra, EPUB is highlights-only. It stops short of describing what happens on failure modes or the exact return/output, but covers the key behavioral constraints.

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 dense but efficient — a single substantial paragraph followed by concrete examples. Every sentence carries functional value. It's slightly long and could benefit from bullet formatting for the two modes and coordinates, but the content density justifies the length given 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?

With an output schema present and 7 parameters at 0% schema description coverage, the description compensates comprehensively. It covers mode exclusivity, coordinate conventions, text-matching limitations, functional prerequisites, and includes two concrete invocation examples. This is complete for a tool of this complexity.

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%, so the description must fully compensate. It explains text matching against the text layer, rect coordinate system normalization ([0,1] with (0,0) at top-left, page-relative width/height), the attachment_key distinction (NOT the parent item key), and page semantics (1-indexed, chapter for EPUB). It also explains defaults (color hex '#ffd400') and optional params. This exceeds what the bare schema provides.

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 it 'Create[s] an annotation on a PDF attachment' with a specific verb+resource. It distinguishes the two modes (text= highlights, rect= area box) and explicitly calls out the EPUB limitation (highlights only), which separates it from sibling tools like zotero_update_annotation and zotero_delete_annotation.

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 when-to-use guidance: exactly one of two modes per call, both/neither is an error. It references sibling tools for prerequisites (zotero_get_item_children finds attachment key, zotero_get_page_layout for region detection) and states requirements (PyMuPDF, writable library). This is clear contextual guidance for correct invocation.

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