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

Annotations only flag destructive/openWorld; the description adds genuinely new behavioral facts: customer notes are emailed (an irreversible outbound side effect), content is sanitized via wp_kses_post, and the Royally execution layer holds the call for human approval so nothing changes on the site until then. It does not say what to expect on denial/timeout or how the approval state is surfaced.

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-loads the core action, then the note-type distinction, then the safety/approval caveat — a sensible order. Mild waste in the parenthetical '(site: demo.royalplugins.com)', which repeats the site_id enum description already in the schema.

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 mutating, open-world write tool with no output schema, it covers the essentials: what is written, who sees it, sanitization, and the human-approval gate on execution. The main remaining gap is the response/return shape and whether duplicate notes are possible (idempotentHint=false is not explained).

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 baseline is 3; the description goes beyond it by spelling out the real-world consequence of customer_note=true (email to the customer plus display on their order view) versus false (internal staff timeline) and by explaining the HTML sanitization applied to note. order_id and site_id add nothing beyond the schema.

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 ('Add a note to a WooCommerce order') and immediately splits the operation into its two meaningful modes (private vs customer), which no sibling tool (wc_update_order, wp_create_comment) covers. An agent can identify this as the order-note writer without opening the 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?

Gives clear in-tool guidance on which variant to use — private = staff timeline only, customer = emailed and visible to the customer — which is effectively the key when-to-choose decision. It does not name an alternative sibling (e.g. when to use wc_update_order or wp_create_comment instead), so it stops short of explicit routing.

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