Create WooCommerce Order Note

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

Annotations set readOnlyHint=false and destructiveHint=false, which aligns with the description of adding a note (non-destructive write). The description adds value by disclosing that customer-visible notes trigger an email, which is a behavioral side effect not evident from annotations alone.

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 concise and well-structured: an initial summary, an Args list, Returns, and an Example. Every sentence adds necessary information with no redundancy.

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 tool with no output schema, the description states 'Returns: The newly created note object', which is sufficient. It covers the two note types, parameter defaults, and provides an example. Minor omission: no mention of error conditions or prerequisites (e.g., order must exist).

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?

The input schema already describes all 4 parameters (100% coverage). The description enhances this by clarifying that customer_note=true emails the customer and that response_format defaults to 'markdown'. The example also demonstrates parameter usage, adding practical meaning.

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 clearly states 'Add a note to an order' and distinguishes customer-visible from internal notes. Sibling tools like woocommerce_list_order_notes and woocommerce_create_order_refund have different purposes, so the tool is easily distinguishable.

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?

Provides a concrete usage example ('let the customer know order 100 has shipped') and explains the customer_note parameter effect. However, it does not explicitly state when not to use this tool vs. alternatives like updating the order or sending a custom email.

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