zotero_update_collection

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

With no annotations provided, the description carries the full transparency burden. It discloses important behavioral traits: the key, subcollections, and item membership are preserved; a collection cannot be moved under itself or a descendant; to_top_level removes it from any parent; and at least one change must be supplied. It does not cover write-permission requirements or error/conflict behavior, so it is strong but not exhaustive.

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 front-loaded with the core purpose, followed by concise parameter guidance, a constraint, a helper-tool pointer, and a concrete example. Each sentence earns its place, and the structure makes the tool easy to scan and use correctly.

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 4-parameter mutation with no annotations and no schema descriptions, this definition is largely complete: all parameters are documented, constraints are stated, and an output schema exists so return-value details are not required. A minor gap is the lack of explicit guidance on combining parent_collection with to_top_level or handling conflicting inputs, keeping it from a perfect score.

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 0%, so the description must compensate, and it does. Every parameter is explained beyond its schema type: collection_key is the 8-character key, name can be omitted, parent_collection accepts a key or name and has a self/descendant restriction, and to_top_level moves the collection out of any parent. The 'pass at least one change' rule adds useful guardrail semantics.

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 specific verb and object: 'Rename a collection or move it under a different parent, keeping its key, subcollections and item membership.' This clearly distinguishes it from related siblings like zotero_create_collection, zotero_delete_collection, and zotero_update_item. The mention of the 8-character collection key adds practical precision.

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 gives clear context for when to use this tool: renaming or reparenting a collection while preserving its contents. It also explicitly directs the agent to zotero_search_collections to find keys. It does not name alternative tools to avoid, but the action is specific enough that an agent can infer the appropriate situation.

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