product_publish_from_brief

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

Annotations already declare the write/open-world/non-idempotent profile, so the description only needs to add what they don't cover. It does add real value: `brief_path` is confined to allowed directories, draft defaults to true, and warnings can be raised when fewer than 4 main images exist because AI cannot generate real photos. The enumerated return fields are largely redundant with the output schema, keeping this short of a 5.

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?

Front-loaded with the purpose, then input modes, then brief contents, then outputs — a sensible information hierarchy with no filler sentences. It is dense for a single paragraph, but every clause contributes.

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 AI-enrichment tool the description covers input modes, required brief fields, defaults, and failure warnings, and an output schema exists to carry return details. The only notable gaps are the unexplained `account_key` and the absence of any note about authorization prerequisites or repeat-call behavior.

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 0% and `brief` is an untyped object, so the description carries the full burden — and it does, spelling out the required brief keys (description, category_id, images, price with unit/moq/tiers, facts with place_of_origin/material). It also clarifies `brief_path` and the `draft` default. `account_key` is left unexplained, which prevents a top score.

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?

States a specific verb and resource ('Publish a product') plus the defining scope ('from a minimal brief — the seller provides only facts; Claude enriches the rest'). This scope is exactly what separates it from the sibling product_publish, so an agent can route between them without opening either schema.

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 explains how to supply input (inline `brief` or `brief_path`) and what the brief must contain, which is genuine usage context. However, it never says when to choose this tool over product_publish or product_render_draft, nor any precondition such as authorization or schema lookup. Usage is implied rather than stated.

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