Annotate a PDF (highlights, notes)

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

Annotations already indicate readOnlyHint=false, and the description adds valuable behavioral detail: delete 'trashes' annotations, writes go to the running Zotero desktop app via connector protocol or local API, and highlights require a position to render. This goes beyond the annotation metadata without contradicting it.

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 front-loaded with a clear overview, then efficiently covers action-specific behavior, position requirements, and write targets. Every sentence adds useful operational detail without fluff, and the structure mirrors the tool's action-based usage.

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 complex tool with six parameters, nested annotation objects, and no output schema, the description covers the essential usage paths: add with required parent/annotations, delete with annotation_keys, position semantics, and write destination. Remaining parameters like library_id and tags are documented in the schema, so the description is sufficiently complete.

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?

The description adds substantial meaning beyond the schema: it explains that action:'add' needs parent and annotations, defines the exact highlighted passage requirement, specifies the position format with PDF points and bottom-left origin, and clarifies that without a position highlights cannot render. This compensates for the 67% schema coverage.

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 a specific verb and resource: 'Add or delete Zototero PDF annotations (highlights, underlines, notes)' and explicitly ties them to the same objects created in the Zotero PDF reader. This clearly distinguishes the tool from siblings like zotero_attachment or zotero_attach_file.

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 clear context for when to use the tool: for adding or deleting PDF annotations with add/delete actions. It explains the write target (desktop app vs cloud Web API) but does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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