zotero_get_collection_items

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

With no annotations provided, the description carries the full burden and delivers: it explains what each detail level returns and omits ('summary' has no abstracts, 'full' has abstracts), states that PDF/notes indicators are included, and discloses key behaviors — subcollection traversal is off by default and pagination is driven by an offset that the response explicitly names. This gives an agent a reliable model of cost and output shape before invoking.

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?

Roughly 110 words, front-loaded with the core purpose before layering in detail modes, behavioral flags, pagination, and a routing tip. Every sentence carries distinct information, though the phrase 'and this tool's previous behaviour' adds minor redundancy.

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?

An output schema exists, so return-value documentation is covered elsewhere. The description covers the meaningful behavioral surface for a 5-parameter tool: mode semantics, subcollection behavior, pagination protocol, and an alternative-tool pointer. The only thin spot is the slightly ambiguous 'Includes PDF/notes indicators' (unclear whether keys_only omits them), which is a minor gap given the rich output schema.

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 high (80%) so the baseline is 3, but the description adds genuine value beyond the schema: it decodes the detail enum values ('keys_only' minimal, summary without abstracts, full with abstracts), explains include_subcollections' default and its equivalence to Zotero's checkbox, and reveals that the response names the next offset — a protocol detail the schema only hints at via 'Index of the first item.'

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?

Opens with a specific verb+resource ('Get all items in a specific Zotero collection') that is immediately distinguishable from siblings like zotero_get_collections (lists collections) and zotero_get_item_metadata (single item). The detail-mode breakdown further clarifies the tool's scope, and explicitly naming zotero_semantic_search as a faster alternative reinforces what this tool is not.

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 an explicit routing rule: for topic-focused paper finding, use zotero_semantic_search instead because it is faster and returns only relevant results. Also gives contextual guidance on paging through large collections and on include_subcollections matching Zotero's own 'Search subcollections' checkbox. The when-to-use for this tool itself — needing all items in a collection — is clearly implied by the opening sentence.

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