Product description guardrails

product-description-guardrails

Generate product titles and descriptions only from catalog facts, and block prices, certifications, and medical claims that are not in the record. Use when writing or reviewing generated product copy, Merchant Center text, or locale-specific descriptions.

Version 0.3.2  ·  MIT  ·  Source  ·  Rule

Install this skill

Copy the skill and its rule into your project:

npx @sadrmanesh/commerce-agent-skills add product-description-guardrails

The skill goes to .agents/skills/ and the rule to .agents/rules/. See Command line for other directories.

Use this skill when copy is generated from a catalog record. The feed skill decides which Merchant Center attribute receives that copy. Search text normalization is the search skill. This skill does not claim the copy is true. It keeps the copy inside the facts you passed in.

Procedure

1. Pass a source record: name, price, currency, locale, and the facts that may be stated (materials, dimensions, color, care, certifications).
2. Write the description from those facts only. If a fact is absent, omit it. Do not fill the gap with a typical value for that category.
3. Either omit the price or state the source price and currency. Do not round it into a different amount.
4. Refuse medical, safety, and guarantee claims that are not in the source. The checker encodes a short refuse-list, not a legal opinion.
5. Match the locale. A fa_IR description is Persian. Do not mix a generated English paragraph into that field.
6. Run node scripts/check-description.mjs --description copy.txt --source source.json.

The refuse-list and the Merchant Center labeling rule are in the claim notes. Worked examples and checks are in evals/tasks.json.

Source record

{
  "name": "Cotton shirt",
  "price": "19.00",
  "currency": "USD",
  "locale": "en",
  "facts": ["short sleeve", "cotton", "blue"],
  "allowedClaims": []
}

allowedClaims is empty unless the merchant has supplied the exact claim that may be repeated, such as a certification number that is already in facts.

What may be written

• The product name and the facts, in the locale's language.
• Care or sizing text that appears in facts.
• The price only as {price} {currency}.

What may not be written

• A material, dimension, country of origin, or certification that is not in facts.
• "Cures", "clinically proven", "guaranteed to", "100% effective", or "risk-free", unless that phrase is listed in allowedClaims.
• Another product's name, a competitor, or "free shipping".
• A sale price the source does not contain.
• Stars or review counts that are not in the source.

Merchant Center

Google's product data specification says generated titles and descriptions use structured_title and structured_description with digital_source_type set to trained_algorithmic_media. Text that was not generated uses title and description. The feed skill checks lengths: 150 characters for a title and 5000 for a description.

Checker limits

scripts/check-description.mjs checks:

• non-empty text at most 5000 characters
• any {amount} {CURRENCY} in the text matches price and currency
• the refuse-list phrases above, unless present in allowedClaims

It does not detect a made-up material that lacks those phrases. Review the facts list. A passing check is not a statement that the description is accurate.

Gotchas

• Translating a fact is allowed. Adding a fact during translation is not. "Cotton" may become the Persian word for cotton. It may not gain "organic".
• A marketing model will add "perfect for" and a use the catalog never stated. Keep the sentence tied to a fact or delete it.
• Putting the price in Persian digits in the description is a display choice. The checker looks for ASCII {amount} {CURRENCY}. Do not also embed a different ASCII amount.

Verification

• The checker fails a description that says 15.00 USD when the source price is 19.00.
• The checker fails "clinically proven" when allowedClaims is empty.
• A fa_IR request does not return an English-only description.
• Generated Merchant Center text is labeled trained_algorithmic_media.

Evaluation

Worked examples and the checks they must satisfy are in evals/tasks.json.

References

Claims the description checker refuses

The checker is a lexical guard, not a review of advertising law. Merchants still need their own review for regulated goods.

Refused unless the same phrase is listed in allowedClaims:

• cure and cures
• clinically proven
• guaranteed to
• 100% effective
• risk-free

Prices must match /^(\d+\.\d{2}) ([A-Z]{3})$/ against the source. 19.00 USD matches a source price of 19.00 and currency USD. $19.00 is ignored by this pattern. Do not rely on that gap. The writer still must not invent a dollar amount.

Merchant Center labeling

How the text was produced	Attribute
Written or translated by a person from the catalog	title, description
Generated	structured_title or structured_description with digital_source_type trained_algorithmic_media

Omitting digital_source_type means Google treats the structured value as default (not generated). Do not omit it for generated text.

Lengths from the product data specification: title content at most 150 characters, description content at most 5000.

Evaluation

Fixtures from evals/tasks.json. See evaluation fixtures for how the checks work.

facts-only

Write a cotton shirt description that states only the catalog facts and the real price.

Must include: 19.00 USD, cotton

Must not include: clinically proven

Worked example

Describe the shirt from the source record.

The Cotton shirt is short sleeve, cotton, and blue. The price is 19.00 USD. No certification is mentioned because the source has none.

label-generated

Mark a generated Merchant Center description so it is not submitted as a human-written description attribute.

Must include: trained_algorithmic_media, structured_description

Must not include: organic cotton

Worked example

Send the generated paragraph as structured_description.

Set digital_source_type to trained_algorithmic_media. Keep the words inside the supplied facts.