Create Collection

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds real value by naming what is mutated ("workspace sidebar metadata") and what is not (documents), but says nothing about permissions, duplicate-name behavior, or whether rules are applied retroactively.

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?

Two sentences, front-loaded with the action and scope, zero filler. The non-document clarification is placed immediately after the core statement where it matters most.

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?

With an output schema present, return values need no explanation, and annotations plus a fully documented schema cover parameters. What remains thin is the relationship to update_collection_rules / add_doc_to_collection and any setup assumptions, but for a simple create call the description is nearly sufficient.

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 100% and the nested filter/operator unions are thoroughly documented in the schema. The description only echoes "optional rules" and adds no semantics (e.g., what the allow-list means or how match:any interacts with filters), so the baseline 3 applies.

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?

States a specific verb and resource ("Create a new AFFiNE sidebar collection with optional rules") and adds a negative scope clause ("does not create documents") that separates it from create_doc/create_semantic_page. It does not explicitly distinguish itself from update_collection, delete_collection or add_doc_to_collection, but the purpose itself is unambiguous.

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?

There is no when-to-use guidance: nothing says use this first and then add_doc_to_collection, nor when to prefer update_collection over re-creating. The "does not create documents" line clarifies scope but is not a usage rule, so the agent must infer the workflow from sibling names.

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