Add Note

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds valuable behavioral context beyond the annotations: the note is created as a child of the specified item and supports HTML formatting. This clarifies the structural relationship and input format without contradicting the annotations.

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 front-loaded with the main purpose. The Args section is clearly formatted and each sentence serves a purpose. The only slight inefficiency is the repetitive phrase 'the note' in the second sentence, but overall it is well-structured and not verbose.

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 simple add-note tool, the description covers the essential behavioral details (child note, HTML support) and parameter meanings. An output schema exists, so return values are handled structurally. The description doesn't mention what happens if the parent item doesn't exist, but given the tool's simplicity and annotations, this is acceptable.

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?

With 0% schema description coverage, the Args section in the description compensates by explaining both parameters. 'item_key' is described as 'The parent Zotero item key to attach the note to,' and 'note' as 'The note content (plain text or HTML).' This adds meaning beyond the bare schema titles, though the descriptions are concise and could specify formatting limitations or length constraints.

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 'Add a note to a Zotero item,' which clearly identifies the action (add) and the resource (a note). It distinguishes itself from siblings like delete_note and update_note by explicitly focusing on creating a new note as a child of an item.

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 context that the note is attached to a specified parent item and mentions HTML formatting, but it does not explicitly state when to use this tool versus alternatives (e.g., update_note for editing, delete_note for removal). Usage is implied rather than clearly delimited.

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