gold_list_products

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

The description reveals critical behavioral traits: it is bring-your-own-key (BYOK), requiring WC_STORE_URL and consumer key/secret, and it fails closed if those are missing rather than returning fabricated data. Since no annotations are provided, this disclosure carries the full burden of behavioral transparency. It does not describe return format or pagination, but the credential and fail-closed behavior are valuable and beyond the schema.

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 a single, front-loaded sentence that gets straight to the action and endpoint. The 'Gold PRO $29' phrase is marketing noise that doesn't help invocation, but the rest is dense and efficient. It's reasonably concise while communicating the essential operational constraint (BYOK, fail-closed).

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 no annotations, no output schema, and eight optional parameters, the description needs to explain defaults, response shape, and filtering behavior. It only covers the endpoint, credentials, and fail-closed policy. Important context like pagination defaults, the shape of the returned product list, and how filters combine is missing, so an agent may mis-infer behavior.

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 has only 25% parameter description coverage (page and per_page get descriptions; the other six parameters are bare enums or types). The tool description does not explain any of the parameters, such as how search, status, category, or orderby interact with the endpoint. With low schema coverage and no supplementary description, agents are left to guess parameter meanings.

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 explicitly states the action ('list Woo products') and the exact endpoint ('GET /wp-json/wc/v3/products'). This specific verb+resource clearly distinguishes it from sibling tools like gold_get_product (single product) and gold_list_orders (orders). The 'Gold PRO $29' prefix is extraneous but does not obscure the core purpose.

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?

No guidance is provided on when to use this tool versus siblings, such as gold_get_product for a single product or gold_list_orders for orders. The intended use is implied by the description, but no explicit when/when-not or alternative routing is given. This makes the usage guidelines weak, though not misleading.

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