Zotero Update Collection

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

No annotations are provided; the description gives important behavioral constraints, such as the impossibility of moving under itself or subcollections, and the option to move to top level. It mentions error context (#517) but does not specify whether changes are reversible or what the response format is. It effectively explains core behavior constraints but misses some details.

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 efficient and packs relevant details into a few sentences, but it includes a parenthetical issue reference (#517) that adds little value for an agent. The front-loading of the purpose is good.

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?

Despite having an output schema, expected return details are not explained in the description, but given that an output schema exists, the burden is reduced. The description explains how to find keys (via zotero_search_collections) and provides an example, making it sufficiently complete for most agent use cases.

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%, but the description documents each parameter explicitly: collection_key as the key to change, name as optional new name, parent_collection as key or name, and to_top_level as moving out of any parent. It even provides an example that shows typical usage.

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?

Clearly states topics of an update, mentions two specific actions (rename, move parent), and explains the impact on preservation (keeps key, subcollections, membership).

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 guidance on usage by mentioning that at least one change is required and that a collection cannot be moved under itself or its own subcollections. Could be strengthened by explicitly contrasting with zotero_create_collection or zotero_delete_collection, but the restriction is stated.

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