zotero_synthesize_annotations

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

No annotations are provided, so the description carries the full burden. It discloses the tool is non-LLM (only gathers and groups), explains the output format differences, and mentions the limit to keep calls tractable. It does not explicitly state the tool is read-only, though that is strongly implied. Given the tool's benign nature, this is solid coverage.

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 fairly long but every sentence earns its place. It front-loads the core purpose, then systematically covers each parameter, the output structure, usage guidance, and an example. It could be tightened slightly, but it is well-organized and not wasteful.

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?

Given the tool's complexity (4 optional parameters, an output schema, and a clear role in a synthesis workflow), the description covers purpose, parameters, output, behavioral expectations, usage context, and a concrete example. Nothing an agent needs to correctly invoke it is missing.

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 100% and the schema already includes descriptions for each parameter. The tool description goes further by explaining collection_key's 8-character format and scope behavior, tag's accepted input formats, limit's purpose, and format's output differences. This adds meaningful context beyond the schema, though not an enormous amount since the schema is already descriptive.

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 states a specific verb ('Collect... organize') and a clear resource (highlights, annotations, notes) across a scope, and it explicitly distinguishes itself from siblings by noting it does NOT call an LLM and produces a per-paper digest. This leaves no ambiguity about what the tool does relative to the many other Zotero retrieval tools.

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?

It clearly says 'Use this before writing a thematic review' and gives an example call. It also explains what the tool does NOT do (no LLM), which sets expectations. However, it does not explicitly name alternatives (like zotero_get_annotations or zotero_get_notes) or state when one would prefer those, so it falls just short of fully explicit when/when-not guidance.

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