Add note

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, and the description goes well beyond them: it names the return value (card_id), specifies plain-text handling (line breaks become paragraphs, Markdown is not converted), notes the free-plan 100-card quota consumption, and states that no notifications fire. It stops short of disclosing failure modes or permission requirements (e.g., whether the caller must be an editor).

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 tight paragraphs, front-loaded with placement and followed by consequences in a logical order. The opening sentence ('Note card with plain text, added to a board's Unsorted panel') partially duplicates the first clause of the next sentence, a small redundancy in an otherwise dense block.

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 only two well-documented parameters and no output schema, the description covers everything an agent needs: return value (card_id), text formatting behavior, quota impact, visibility/notification behavior, and the undo path. Nothing material is missing for correct invocation.

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 coverage is 100%, so the baseline is 3; the description adds genuine meaning by clarifying the text format contract — Markdown is not converted — which the schema's 'Each line becomes a paragraph' does not make explicit. No extra detail is given about the board_id/URL acceptance already covered in the schema, so it is not a 5.

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 ('Adds one note card') and pins down both placement ('on top of the board's Unsorted panel') and return value ('returns its card_id'). The 'plain text' framing plus the Unsorted-panel destination is enough to separate it from add_todo_list, add_link, and edit_note without opening a schema.

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?

Usage context is implied but never explicit: nothing says when to choose this over add_todo_list/add_link or, once the card exists, edit_note. What it does offer — free-plan card limit, editors see it, nobody is notified, undo by trashing in Milanote — informs the decision to call it but does not function as when/when-not routing.

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