Writing Custom Instructions

Custom instructions are natural language prompts that guide the AI’s decision-making during classification. They let you encode your business logic, handle edge cases, and resolve ambiguity without writing code. This guide explains how to write effective instructions that improve classification accuracy for your specific products.

What Custom Instructions Do

Custom instructions influence how the AI selects categories during Step 2 of the classification pipeline. When evaluating candidates, the AI considers:

1. The product description
2. The 15 candidate categories with relevance scores
3. Taxonomy structure and relationships
4. Your custom instructions

Well-written instructions help the AI make better decisions when multiple categories seem equally valid or when product descriptions contain ambiguous information.

What Instructions Cannot Do

Custom instructions cannot:

• Override the candidate generation process (Step 1)
• Force the AI to select categories that aren’t in the candidate set
• Replace detailed product descriptions
• Compensate for fundamentally incorrect or misleading product information

Instructions guide selection among existing candidates—they don’t create new options or bypass the classification pipeline.

When to Use Custom Instructions

Custom instructions are most valuable for:

Recurring edge cases : Products that consistently return unexpected categories or fall into ambiguous zones

Business logic : Company-specific rules about how products should be categorized

Platform requirements : When your sales channel has specific categorization preferences

Disambiguation : Products that legitimately fit multiple categories where you need a tiebreaker

Category preferences : When you prefer one category over another for products that could fit both

When Not to Use Instructions

Don’t use custom instructions for:

• One-off issues : If only a single product has a problem, improve its description instead
• Compensating for bad descriptions : Fix the description rather than instructing around it
• Overly broad rules : Instructions that try to handle every possible case become ineffective

Writing Effective Instructions

Think Like a Colleague

Write instructions as if you’re coaching a human colleague on how to classify products. Use clear, everyday language and be specific about the situations you’re addressing.

Good:

For phones without contract information, default to unlocked unless the description explicitly mentions contract or pre-paid plans.

Too vague:

Classify phones correctly.

Too technical:

If product.category == “phone” && !contract_type.present? then select unlocked_category.

Be Specific About Conditions

State clearly when your instruction applies. Good instructions have two parts:

1. The condition : What situation triggers this rule
2. The action : What the AI should do in that situation

Example:

• Condition: When a product could be either clothing or an accessory
• Action: Prefer clothing if the item is worn directly on the body

Combined:

When products could be clothing or accessories, prefer clothing if they’re worn on the body.

Focus on Disambiguation

Instructions work best when they help the AI choose between legitimately similar options. Focus on providing tiebreakers rather than general classification guidance.

Effective (provides tiebreaker):

When choosing between material-based and style-based clothing categories, prioritize material over style.

Less effective (too general):

Classify clothing items in the most appropriate category.

Use Examples When Helpful

If your rule is complex, include examples to clarify:

For multi-purpose products, classify by primary use case. For example, a fitness tracker with smart features goes under fitness devices, not smartwatches, because fitness tracking is its primary function.

Keep It Concise

The AI evaluates your instructions alongside product descriptions and candidate categories. Long, rambling instructions are less effective than concise, focused ones.

Concise:

Gaming peripherals go under gaming, not general computer accessories.

Too long:

When you encounter products that are peripherals used for gaming, such as gaming keyboards, gaming mice, or gaming headsets, please categorize them under the gaming category tree rather than placing them in the general computer accessories section, unless they are specifically marketed as dual-purpose devices.

The AI understands context—you don’t need to over-explain.

Common Instruction Patterns

Default Assumptions

Tell the AI what to assume when information is missing:

Default to unlocked for phones unless description states contract or pre-paid.

Assume products without voltage specifications are for standard household use (110-120V in US, 220-240V in EU).

When power source isn’t specified for tools, assume corded electric unless product name includes “cordless” or “battery.”

Prioritization Rules

Specify which characteristic matters most when multiple apply:

For clothing, prioritize material over style (e.g., “leather jacket” goes under leather clothing, not jackets).

Prioritize age group over gender for children’s products.

When products serve multiple purposes, classify by primary function over secondary features.

Category Preferences

State clear preferences between similar categories:

Prefer “Home Office Furniture” over “Office Furniture” for products marketed to home users.

Choose “Athletic Shoes” over “Casual Shoes” if the product mentions any sport or exercise context.

Smart home devices go under home automation, not their traditional categories (e.g., smart locks go under home automation, not door hardware).

Specificity Guidance

Tell the AI when to be specific vs. general:

When products fit multiple subcategories equally well, choose the parent category rather than guessing.

For generic products without distinguishing features, use the broader category (e.g., “phone case” without material or style details goes under generic phone cases).

Be specific when the description provides clear distinguishing information (e.g., “leather bifold wallet” should go to the most specific leather wallet category).

Product Type Disambiguation

Handle products that could fit multiple types:

Smartwatches with fitness features go under smartwatches, not fitness trackers.

Convertible laptop-tablet devices go under laptops, not tablets.

Multi-tools that include knives go under multi-tools, not knives.

Regional or Language Rules

Specify regional preferences if relevant:

For UK English spellings (colour, favourite), classify identically to US English equivalents.

Products described with European sizing should map to the same categories as US-sized equivalents.

Product Type Examples

Electronics

For phones without contract information, default to unlocked unless description explicitly states contract or pre-paid.

Tablets with keyboard accessories remain tablets—only classify as laptops if the description explicitly calls them laptops.

Bluetooth speakers go under portable audio, not smart speakers, unless they mention voice assistants.

Clothing and Apparel

Prioritize material over style for clothing (leather jacket → leather clothing, not jackets).

Athletic clothing goes under activewear even if it could be casual wear.

When gender isn’t specified in product description, choose unisex categories over gendered ones.

Home and Garden

Smart home devices go under home automation, not their traditional categories.

Indoor/outdoor products default to indoor unless description mentions outdoor use or weather resistance.

For furniture without room specification, prefer general categories over guessing the room.

Sports and Outdoors

Classify by primary sport when products serve multiple activities (e.g., cross-training shoes → athletic shoes, not specific sport shoes).

Fitness trackers with basic features go under fitness trackers; advanced ones with apps and payments go under smartwatches.

Camping gear that could be tactical/military goes under camping unless description emphasizes tactical use.

Beauty and Personal Care

Products marketed for multiple genders go under unisex categories.

Organic/natural products go in their functional category first (e.g., organic shampoo → hair care, not a separate organic products category).

Professional salon products and consumer products go in separate categories when available.

Testing Your Instructions

After writing custom instructions, validate them with real products:

Test With Edge Cases

Try products that specifically trigger your instruction:

If your instruction is:

Gaming peripherals go under gaming, not general computer accessories.

Test with:

• Gaming keyboard
• Gaming mouse
• RGB gaming headset
• Mechanical keyboard (gaming-capable but not marketed as gaming)

Check for Unintended Effects

Ensure your instruction doesn’t negatively affect other products:

If your instruction is:

Smart home devices go under home automation.

Verify it doesn’t misclassify:

• Smart TVs (should stay under televisions)
• Smartphones (should stay under phones)
• Smart appliances (might need additional guidance)

Verify Green Status Results

Good instructions should increase green indicators (AI-selected) and decrease yellow/black results for the products they target. Test before and after adding instructions:

Before instruction:

• Gaming keyboard → Computer Accessories (🟡 Yellow)

After instruction:

• Gaming keyboard → Gaming Peripherals (🟢 Green)

Iterate Based on Results

If your instruction doesn’t improve results:

1. Make it more specific : Add conditions that narrow when it applies
2. Provide examples : Help the AI understand your intent
3. Split complex rules : Break one instruction into multiple focused ones
4. Check candidate generation : Ensure the desired category exists in candidates

Anti-Patterns to Avoid

Too General

Bad:

Classify products accurately.

Why: Provides no actionable guidance

Better:

When products fit multiple categories, prefer the more specific one.

Contradictory Instructions

Bad:

Prioritize material over style for clothing. Prioritize style over material for apparel.

Why: Clothing and apparel are the same—this creates confusion

Better:

Prioritize material over style for clothing items.

Overly Prescriptive

Bad:

All products containing the word “leather” must go in category el-42-3-5-2 regardless of context.

Why: Overrides the AI’s semantic understanding and forces incorrect categorizations

Better:

For clothing and accessories, prioritize material over style (leather jacket → leather clothing).

Compensating for Bad Data

Bad:

If the description just says “phone” with no other details, assume it’s a flagship smartphone.

Why: Instructions shouldn’t compensate for insufficient descriptions

Better: Fix the product description to include necessary details

Trying to Handle Everything

Bad:

For electronics, consider the following rules: [15 paragraphs of detailed instructions covering every possible edge case]

Why: Overly long instructions become noise

Better: Write focused instructions for your most common issues, not every possible scenario

Combining Instructions

You can write multiple instructions to handle different situations. Each instruction should focus on a specific issue:

For phones without contract information, default to unlocked unless description states contract or pre-paid.

Gaming peripherals go under gaming, not general computer accessories.

When clothing could be categorized by material or style, prioritize material.

Smart home devices go under home automation, not their traditional categories.

The AI evaluates all instructions together when making decisions.

Keep Related Instructions Together

Group related rules for clarity:

Good structure:

For phones without contract information, default to unlocked.
Smartphones with basic features go under smartphones, not feature phones.

Prioritize material over style for clothing.
Athletic clothing goes under activewear even if casual-appropriate.

Real-World Examples

E-commerce Store (Mixed Catalog)

Challenge: Products that could be gifts or their functional category

Instruction:

Products described as “gift sets” or “gift boxes” go under gifts, not their contents’ categories. Individual products that happen to be gifted go in their functional categories.

Result: Clear distinction between gift-marketed products and regular products

Electronics Retailer

Challenge: Refurbished products being misclassified

Instruction:

Refurbished or renewed products belong in the same category as new equivalents—condition doesn’t change the product type.

Result: Refurbished laptops correctly go under laptops, not accessories

Fashion Retailer

Challenge: Unisex products defaulting to men’s categories

Instruction:

When gender isn’t specified or products are marketed as unisex, choose unisex categories over gendered ones.

Result: More accurate categorization for gender-neutral clothing

Outdoor Gear Store

Challenge: Multi-sport products scattered across categories

Instruction:

When products serve multiple outdoor activities, classify by the primary activity mentioned first in the description, or use general outdoor equipment if no activity dominates.

Result: Consistent categorization for versatile gear

Refining Over Time

Custom instructions aren’t set-and-forget. Refine them as you:

• Add new product types : New inventory may need new guidance
• See patterns in misclassifications : Recurring issues suggest instruction opportunities
• Change business rules : Update instructions when your categorization strategy changes
• Get platform feedback : If a sales channel rejects certain categorizations, adjust instructions

Maintenance Best Practices

1. Document why instructions exist : Note the problem each instruction solves
2. Review quarterly : Check if instructions still apply to current inventory
3. Remove obsolete rules : Delete instructions for discontinued product types
4. Test after changes : Verify updates don’t break existing classifications

API Integration

Apply your tested instructions in API requests:

{
  "product": "RGB mechanical gaming keyboard",
  "taxonomy": "shopify",
  "customInstructionsForAi": "Gaming peripherals go under gaming, not general computer accessories. For phones without contract information, default to unlocked.",
  "leafsOnly": false,
  "fallbackToBestGuess": true
}

The API evaluates instructions identically to the Playground, ensuring consistent results.

Next Steps

After writing custom instructions:

1. Test in the Playground : Validate with products that trigger your rules
2. Check different strategies : See how instructions perform with various configurations (see Classification Strategies)
3. Understand the pipeline : Learn how instructions fit into the classification process (see Classification Pipeline and Settings)
4. Monitor results : Track green/yellow/gray distribution as you refine instructions

Good instructions improve classification accuracy without requiring changes to your product data or classification code.