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

Annotations already declare this as a non-idempotent, destructive, open-world write. The description adds genuinely useful context beyond them: it uses local WordPress authentication so no WooCommerce REST API keys are needed. However, it says nothing about side effects, what an empty zone does by default, or whether repeated calls duplicate zones, which matters for a tool flagged idempotent=false and destructive=true.

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 short sentences with the purpose front-loaded and no padding. The second sentence is arguably marginal, but it does convey authentication information an agent might otherwise assume requires API keys.

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?

This is a destructive write with no output schema and an unconstrained nested payload, so the description should carry more weight than it does. Nothing explains what the created zone looks like on return, which fields are valid, or what happens to default/unassigned locations, leaving the caller to guess at a required object's shape.

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?

site_id is fully documented in the schema. The required zoneData object, by contrast, is declared with empty properties and additionalProperties=true, so neither schema nor description tells the agent which fields (name, locations, ordering) to supply. Saying only 'Shipping zone fields to create' adds no meaning over the parameter name, leaving a required payload effectively unspecified.

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 first sentence states a specific verb and resource: 'Creates a WooCommerce shipping zone.' That is enough to separate it from the get/update/delete shipping-zone siblings. The second sentence adds implementation detail about authentication rather than sharpening the purpose, and no sibling is named explicitly.

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 never says when to create a zone versus updating an existing one, whether a zone must exist before adding methods or locations, or what prerequisites (permissions, site connection) apply. The only prerequisite guidance, calling list_sites first, lives in the schema, not the description.

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