zotero_apply_paper_import

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

The description goes well beyond the annotations by detailing fail-closed checks, metadata resolution, collection union versioning, non-destructive guarantees ('Never removes memberships, merges items...'), and the desktop sync implication. This rich behavioral disclosure matches the annotations and adds critical safety context.

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?

Three sentences, each earning its place: action+scope, process details, and safety/prerequisite notes. Front-loaded with the main verb, the description is dense but not bloated, avoiding any filler.

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 tool is moderately complex (batch write, checks, unions), and the description covers the process, exclusions, prerequisites, and desktop sync behavior. It does not mention error handling or rate limits, but an output schema exists, which covers return values, so the missing bits are not critical.

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?

With schema coverage at 50%, the description compensates by explaining that 'items' is the preflighted batch (up to 50 papers) and that 'confirm=true' authorizes writes. It also adds meaning to collection_keys/ID fields via 'resolves DOI/PMID/arXiv metadata' and 'versions collection unions,' but it does not explicitly map each field beyond the schema.

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 clear verb and resource: 'Apply a preflighted batch of up to 50 papers through the official Zotero Web API.' It explicitly distinguishes itself from the planning sibling tool by saying 'preflighted,' and lists concrete sub-actions (rescans, cloud checks, metadata resolution, collection unions) that fully define the tool's purpose.

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 phrase 'Apply a preflighted batch' clearly indicates this tool is for executing a prior planning step, and 'Requires confirm=true' states a precondition. It gives clear context for use but does not explicitly name the alternative (e.g., 'use zotero_plan_paper_import for preflight'), so it stops short of a full 5.

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