Attach a note to a Zotero item

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

The annotations already indicate readOnlyHint=false (write) and destructiveHint=false, but the description adds valuable behavioral context: plain text is converted to simple HTML paragraphs, and pre-existing HTML is passed unchanged. It also clarifies the dry_run behavior (shows payload without writing). This goes beyond the structured annotations and helps the agent predict side effects.

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 compact and well-structured. The opening sentence states the core purpose, followed by a concise args list that maps directly to the parameters. Returns are specified in one line. Every sentence adds information; there is no fluff or repetition. The front-loading ensures an agent quickly understands the tool's function.

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 all four parameters, the conversion behavior, and the return value (new note key or dry_run payload). The output schema exists, so the return structure is already documented. Minor omissions include prerequisites like authorization or whether the parent item must exist, but these are likely implied by the tool context. Overall, it is sufficiently complete for a note-creation tool.

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 is the only source of parameter meaning. It clearly explains each parameter: item_key (parent item), content (with HTML conversion rules), tags (optional comma-separated), and dry_run (payload preview). This adds significant semantic value that the schema lacks, making the tool callable without external lookup.

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 states a specific action ('Attach a child note to an existing item') with a clear resource and target. This distinguishes it from siblings like zotero_add_item (adds an item) and zotero_update_item (modifies an existing item). The verb 'attach' plus the object 'note' and parent 'item' leaves no ambiguity.

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 does not explicitly state when to use this tool versus alternatives. It implies usage by its purpose, but there is no mention of when not to use it, or what conditions favor zotero_add_item or zotero_update_item. The sibling context is not referenced, so an agent must infer usage from the tool's name and purpose.

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