shopify_find_sample_product

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond annotations, including labeling generated concepts as examples rather than supplier offers or verified products, and constraining image usage to available relevant URLs. This meaningfully reduces the risk of fabricating or misrepresenting results.

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 front-loaded with the main purpose, followed by fallback behavior and constraints. Each sentence adds meaningful guidance, though a little more precision about parameters and output could be included without bloating it.

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 three parameters and no output schema, the description gives enough to select and start invoking the tool, including important labeling and image constraints. However, it does not explain what the tool returns, how limit affects results, or how to determine whether a category lacks suitable samples. Some invocation details remain under-specified.

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 provides structural constraints but no semantic descriptions, so the description must compensate. It explains the query as the basis for generating concepts and clarifies that generatedCandidates drives draft-creation cards. However, the limit parameter is not addressed at all, and generatedCandidates semantics are only partially explained. This is adequate but has clear gaps.

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 verb and resource: 'Find sample products across published Shopify demo catalogs.' It also distinguishes itself from sibling search tools by specifying sample/demo context and the fallback behavior of generating original product concepts rather than searching the full catalog.

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 clear usage context: use it to find sample products, and when no suitable sample exists, generate concepts and pass generatedCandidates. It does not explicitly name alternatives or exclusions, but the demo-catalog scope and fallback conditions give an agent enough context to decide when to invoke it.

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