Manage Zotero collections

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

Annotations indicate readOnlyHint=false (writes) and openWorldHint=true. The description adds context: 'All actions except 'list' write to the cloud Web API.' It also explains the side effect of add_items/remove_items modifying membership. No contradiction with annotations. Full disclosure of write behavior.

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 well-structured with action summaries, but it is somewhat lengthy. It front-loads the list of actions and provides necessary details. Could be slightly more concise, but the information density is high 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?

For a tool with 7 parameters and 7 actions, the description covers the core behaviors well. It mentions that 'list' returns keys/names/parent but does not specify the exact format. No output schema exists, so return values are implied but not fully detailed. Still, it is mostly complete for agent usage.

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 57%, but the description compensates by explaining the action enum in detail, clarifying when each parameter is needed (e.g., collection_key for rename, delete, etc.), and adding meaning like 'omit for top-level' for parent_collection. Adds significant value 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 clearly states the tool can list, create, rename, reparent, delete collections, and move items. It distinguishes itself from siblings like zotero_list_collections by covering all these actions. The verb 'manage' plus the list of actions makes the purpose specific and actionable.

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 guidance for each action (e.g., 'create' needs name, optional parent_collection). It implies when to use each sub-operation but does not explicitly say when not to use this tool in favor of siblings like zotero_list_collections. However, the action list itself effectively directs usage.

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