Карточка товара

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds valuable non-obvious behavior: a non-existent product returns data: null rather than an error, the response caps at 100 variants, and media/metafields are deliberately excluded. This goes well beyond the annotations and helps the agent set correct expectations.

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?

Three dense sentences with no filler: the main return contents are front-loaded, followed by id format, null behavior, and exclusions. Every sentence adds necessary information.

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?

For a single-product read tool with no output schema, the description is complete enough to invoke safely: it covers return contents, limits, id formats, error semantics, and what to use instead for missing data. No critical operational detail is missing.

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 already fully documents the single id parameter, including that it can be a numeric id or a gid://shopify/Product/<id>. The description does not add new parameter meaning beyond restating what the schema provides, so schema coverage carries the weight.

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 uses a specific verb and resource ('Возвращает один товар целиком') and clearly enumerates what is included: description HTML, options, up to 100 variants with prices, stock, SKUs, and inventoryItem id. It also differentiates itself from list_products by focusing on a single full product, and explicitly says media/metafields are not returned.

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 clearly implies this is the tool to fetch one complete product, and it gives an explicit exclusion: media files and metafields are not returned, and for those the agent should use graphql_request. It does not explicitly contrast with list_products, but the single-item scope and the alternative routing for omitted data provide solid usage guidance.

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