Insert or replace a product

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

Goes well beyond annotations: it discloses full replacement (aligned with destructiveHint=true), the MOVES behavior when the data source differs, async processing lag, and that data-quality issues appear later in productStatus.itemLevelIssues instead of API errors. No contradiction with annotations.

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?

Every sentence carries distinct value: core upsert behavior, data-source constraint, MOVES edge case, return shape, async behavior, and price format. The most important semantics are front-loaded and there is no filler.

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 8-parameter write tool with no output schema, the description is remarkably complete: it explains return values, async behavior, error behavior, destructive replacement, and the trickiest parameter format. The remaining parameter details are already in the 100%-covered 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?

Even though the schema already covers parameters at 100%, the description adds critical semantics: the exact price object shape with amountMicros/currencyCode, the 1 unit = 1,000,000 micros conversion, and the meaning of data_source (API-type only). This materially helps an agent construct correct input.

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 states a specific action (Uploads/upserts a product) and resource (API data source), and clearly explains the replace semantics on the contentLanguage~feedLabel~offerId triple. It does not explicitly differentiate from the update_product_input sibling, though the 'fully replaced' wording implies the distinction.

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?

Provides clear when-to-use context: only API-type data sources, with an explicit exclusion (file feeds cannot be written) and an alternative way to create the required source (create_data_source). It stops short of fully routing the agent between insert/replace and the update_product_input sibling, so it is strong but not exhaustive.

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