get_product

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context like 'live' (real-time data) and the effect of quantity on coupons, but no additional behavioral traits (e.g., rate limits, error handling) are disclosed. The bar is lower due to annotations, and the description adds some value without contradicting them.

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 dense but well-structured: a lead sentence capturing the essence, followed by a comma-separated list of returned items. It is front-loaded with the core purpose and each clause earns its place. While long, the complexity of the return data justifies the detail, and it avoids redundancy.

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 the tool's complexity (6 parameters, output schema present, annotations provided), the description covers the return content thoroughly, listing all major data categories. It doesn't address error cases or usage prerequisites, but the required item_id is self-evident and the output schema likely details return structure. The 'live' and 'priced for one variant' framing add important context.

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 description coverage is 100%, so parameters are already documented. The tool description adds semantic value by explaining how parameters affect the output: quantity influences coupon calculations ('what the coupons really give at `quantity`'), city affects the delivery quote, and sku_id selects the variant to price. This goes beyond the schema's isolated parameter descriptions.

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 clearly states the tool's function: 'Full live card for one item, priced for one variant.' It specifies the verb (returns) and resource (product card) and enumerates a comprehensive set of returned data. The purpose is unmistakable and distinct from siblings like search_products (search) and get_reviews (reviews).

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 implies usage: when you need a complete product card for a single item. However, it does not explicitly mention alternatives or when not to use it, nor does it contrast with sibling tools. The detailed output list makes it obvious this is the single-item detail tool, but no explicit guidance is given.

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