Insert or replace a product

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

The description discloses full replacement behavior, the moving effect when a different data_source is used, the return object shape, and asynchronous processing with delayed data-quality feedback. These go well beyond the sparse annotations and give the agent crucial operational context.

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?

A single dense paragraph with each sentence covering a distinct operational point: upsert key, data source type, moving behavior, return fields, async processing, and price format. It is compact and all sentences earn their place, though a more visual structure (bullets) could slightly improve scannability.

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 complex tool with 8 parameters, nested objects, async behavior, and many siblings, the description covers prerequisites, return value, timing, and common pitfalls like the micros format. It also correctly relies on the schema for exhaustive attribute details, making the description complete without being bloated.

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?

Input schema covers 100% of parameters, so the baseline is 3. The description adds genuine value by detailing the price micros format ({amountMicros, currencyCode}) and mentioning availability/condition enums, which are particularly helpful for the open product_attributes object. Still, most parameter descriptions in the schema are already sufficient.

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 it uploads (upserts) a product into an API data source and explains the replacement key (contentLanguage~feedLabel~offerId). It distinguishes itself from siblings like update_product_input and insert_promotion by focusing on product upsert semantics and API data source requirements.

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?

It explicitly says data_source must be an API-type source and names create_data_source as an alternative, and warns that file feeds cannot be written. It also describes the async behavior and that data-quality issues appear later, which helps set correct expectations for when to use this tool.

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