zotero_create_annotation

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

No annotations are present, but the description carries that burden well: it discloses scanned/image-only PDF matching failures, coordinate-system origin and normalization, PDF vs. EPUB behavior, 1-indexed page/chapter semantics, and the PyMuPDF/writable-library requirement. These behavioral facts add critical context not discoverable from the schema.

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 yet well organized: purpose and mode rules first, then key conventions, prerequisites, requirements, and concrete examples. Every sentence carries operational information, with no filler or unnecessary repetition of schema data.

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 7-parameter tool with no annotations and 0% schema description coverage, this definition covers all essential usage knowledge: mode selection, error conditions, coordinate semantics, matching limitations, dependencies, and examples. Since an output schema exists, omitting return-value details is acceptable.

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%, and the description fully compensates by explaining attachment_key vs. parent key, page indexing, exact text matching against the text layer, and rect as normalized [x, y, width, height] with origin and fit constraints. It also adds useful context for optional parameters like color default, comment, and tags.

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 opens with 'Create an annotation on a PDF attachment,' giving a specific verb and resource that clearly distinguishes it from update/delete/get annotation tools. It also differentiates the two modes (text highlight vs. rect area box) and the EPUB/PDF constraints, so an agent knows exactly what the tool is for.

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 explicitly states when each mode applies, warns that passing both or neither text and rect is an error, and directs the agent to companion tools for prerequisites (zotero_get_item_children to find attachment_key, zotero_get_page_layout before choosing rect coordinates). This provides actionable when-to-use guidance beyond a generic summary.

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