Add note

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so the description correctly does not restate that. It goes further and adds what the annotations cannot: the enumeration of failure conditions (missing deck/model, wrong field name, empty first field, duplicate note) and the atomicity guarantee that media failures occur 'before creating anything'. It does not cover partial-success or duplicate-detection semantics in depth, keeping it just short of a 5.

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?

Front-loaded with the action, then return value, then failure modes, then routing tips, then media semantics – a sensible ordering with no filler sentences. It is dense but every clause carries information; only the media sentence runs slightly long relative to the rest.

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 7-parameter write tool with nested media objects and no output schema, the description covers what is created, the return value (note ID), all failure modes, atomicity, and sibling routing. An agent has everything needed to invoke it correctly and interpret failures without opening anything else.

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%, so the baseline is 3, but the description adds cross-parameter behavior the schema cannot convey: media `source` values are constrained to an http(s) URL or an absolute path on the machine running Anki, and each file is appended to the listed fields rather than replacing them. That framing meaningfully informs how to populate `picture`/`audio`/`video` and `fields` together.

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?

Opens with a specific verb+resource ('Creates one note in the given deck using the given model') and explains the downstream effect (Anki generates one or more cards) plus the return value (new note ID). It is clearly differentiated from the sibling add_notes ('for several notes prefer add_notes') and can_add_notes ('check with can_add_notes first').

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?

Names both alternatives explicitly and gives the condition that selects each: can_add_notes for a pre-flight check, add_notes when adding several notes. It also states the precondition that deck and model must already exist, leaving little inference to the agent.

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