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

Beyond the annotations, it discloses the scrape source and fields (name, tagline, description, icons), the override precedence, the permission prerequisite, and the non-publishing side effect — substantial behavior for a mutation tool. The one tension is that scraping an arbitrary external URL reads as open-world activity while annotations declare openWorldHint=false; the description does not resolve that mismatch.

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?

Four tight sentences, front-loaded with the one required input, then override rules, then the publishing caveat, then the permission prerequisite. No sentence is filler; each adds a distinct constraint.

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 six-parameter mutation with no output schema, it covers preconditions, side effects, and field precedence well. The only gap is the return value — it says the product lands on the founder's dashboard but not what identifier or object comes back, which matters for chaining into set_product_public.

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 coverage is 100%, so per-field meaning and limits are already documented; the description still adds value by explaining precedence ('explicit values override the scrape') and the omit-to-scrape semantics that govern all five optional fields. It does not, however, add anything about url normalization or category id formats beyond the schema.

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 verb and resource ('Add a product') plus the minimal input ('from just its URL'), and explains the scrape-and-attach behavior that distinguishes it from list_products or get_product. An agent can tell immediately that this is the creation entry point.

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 states explicitly that only the URL is required and all other fields are optional, that explicit values override scraped values, and that adding never publishes — routing the agent to set_product_public (or the founder) for publication. It also names the prerequisite ('Requires the submit permission'), which tells the agent when the call will be rejected.

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