ls_list_variants

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: pagination via meta.page, the vestigial nature of `price` for tiered variants, and the cross-store enforcement nuance. This goes well beyond annotations and directly prevents costly misinterpretations.

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 information-dense but verbose, containing multiple warnings and notes in a single block. While it is front-loaded with the core purpose and pagination, the pricing warning and cross-store note could be more concisely structured. The length is justified by importance but it lacks crispness.

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?

Given no output schema, the description covers the essential response structure (meta.page for pagination) and provides critical guidance on price accuracy. It also addresses cross-store authorization nuances. An agent has enough to call the tool correctly and interpret results, even without seeing the response schema.

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% with each parameter described. The description enhances this by clarifying productId as an optional filter and implicitly connecting pageSize/pageNumber to pagination. It also highlights that productId becomes required when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, adding semantic depth 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?

The description opens with a clear, specific statement: 'List all variants, optionally filtered by product.' This names the verb, resource, and a filtering option, distinguishing it from single-variant retrieval (ls_get_variant) and price listing (ls_list_prices). No ambiguity about the tool's core function.

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 provides strong usage context: pagination behavior, a warning about the unreliable `price` field, and guidance to use ls_list_prices for authoritative pricing. It also notes the cross-store requirement for productId. However, it does not explicitly state when to avoid this tool in favor of ls_get_variant for a single variant, though that is implied by the listing nature.

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