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

Beyond the readOnly/openWorld annotations, the description discloses useful implementation behavior: the handle is resolved to a Shopify product id, the storefront URL is fixed server-side, and results are normalized. This adds real context the annotations don't carry.

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 and readable in a few sentences. Minor waste in re-specifying intent and limit values that already live in the schema, but overall efficient and well ordered.

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 an output schema present, return values need not be explained, and the description covers input prerequisites and behavior adequately. It is complete for a recommendation lookup, with only marginal usage-context gaps remaining.

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 the schema already documents handle, intent, and limit fully. The description restates the intent and limit semantics verbatim rather than adding new meaning, so the baseline 3 is appropriate.

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 ('Returns normalized recommended products for one Kylie Cosmetics product handle') and hints at differentiation by pointing to kyliecosmetics_product. It is clear what the tool does, though it doesn't explicitly frame itself against the other recommendation-style siblings beyond the storefront scope.

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 final sentence routes the agent to kyliecosmetics_product to obtain a product handle, giving clear prerequisite context. It stops short of stating when-not-to-use recommendations or contrasting related vs complementary intents as usage scenarios.

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