Manage Zotero collections

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

The description explicitly warns that all actions except 'list' write to the cloud Web API, which aligns with and supplements the destructiveHint annotation. It also clarifies that collection membership lives on each item, adding useful behavioral context beyond the annotations, though deletion effects are not detailed.

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 a dense single paragraph organized by action, with the main verb phrase front-loaded and each action clause carrying concrete requirements. It is somewhat monolithic but efficient given seven actions to describe.

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 description covers the full operation set, required parameters, and the list output shape, which is valuable given there is no output schema. It omits details like pagination, write-action return values, and the meaning of library_id/library_type, but overall it gives an agent enough to invoke the tool correctly.

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 maps actions to parameters, such as 'create needs name' and 'reparent can omit parent_collection to move to top level,' adding meaning beyond the raw schema. However, library_id and library_type are left unexplained by both the schema and description, preventing full parameter 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 precise verb-and-resource summary: list, create, rename, reparent, or delete collections, plus moving items in/out. The explicit action list and relation to collection management make it easy to distinguish from sibling tools like zotero_list_collections or tag management.

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?

Each action is paired with its required and optional parameters, effectively telling the agent exactly how to invoke every route. It does not explicitly name alternatives or state when not to use this tool versus siblings, so it stops short of full exclusion guidance.

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