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 of behavioral disclosure. It clearly explains the detail levels (keys_only, summary, full) and what each includes/excludes, states that PDF/notes indicators are included, describes the include_subcollections behavior and its default matching Zotero's own checkbox, and notes that the response names the next offset for pagination. It doesn't cover error cases or authentication, but for a read operation these are minor gaps; the description gives substantial transparency.

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 compact yet dense with useful information. It front-loads the core purpose, then explains the detail options, subcollections, and pagination, and ends with a practical tip. Each sentence adds value; there is no filler or redundancy. The structure is logical and easy to parse.

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 that an output schema exists, the description does not need to explain return values. It covers all key operational aspects: how to control detail, handle subcollections, and paginate large collections. It also mentions the availability of PDF/notes indicators. The tool is fully specified for an agent to call it correctly, with no missing critical context.

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 80%, so most parameters already have descriptions. The description adds meaningful semantics beyond the schema: it explains the detail enum values (keys_only is minimal, summary has no abstracts, full has abstracts), clarifies that include_subcollections returns items from nested collections, and explains that offset is used for paging with the response providing the next offset. This enriches the parameter understanding beyond the raw 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 clearly states the verb and resource: 'Get all items in a specific Zotero collection.' It further distinguishes this tool from zotero_semantic_search by explicitly saying it returns all items in a collection, not filtered by topic. This makes it easy for an agent to select this tool when the goal is to retrieve an entire collection, and differentiate it from siblings like zotero_get_collections (which lists collections, not items).

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 provides explicit when-to-use guidance: it states that for finding papers on a specific topic, zotero_semantic_search is faster and returns only relevant results. This gives a clear alternative and implies this tool is for when you need all items in a collection, regardless of topic. It also explains pagination usage for large collections, guiding the agent on how to page through results.

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