How Opal Instructions Work
A guide to the "When to Use" field
Overview
Instructions allow you to customize how Opal responds to your prompts. Each instruction has a "When to Use" field (also called the "purpose") that tells the system when to apply that instruction to a conversation. Understanding how this field works will help you write instructions that activate precisely when you need them — and stay out of the way when you don't.
How Instruction Selection Works
When you send a message, the system decides which of your instructions are relevant before generating a response. Here's what happens:
1. All active instructions are gathered
The system collects all instructions available to you — organization-wide, workspace-level, and personal instructions — filtering out any that are deactivated.
2. Tool-based instructions are matched first
If an instruction's "When to Use" field references specific tools (e.g., Tools: [generate_image]), it is automatically selected whenever those tools are available. No further evaluation is needed.
3. Remaining instructions are evaluated for relevancy
All non-tool instructions are evaluated using an AI model that reads:
- Your latest message
- The conversation history
- The "When to Use" field of each instruction
The model then decides which instructions are relevant to your conversation.
4. Matched instructions are injected into context
Selected instructions are added to the system prompt so Opal can follow them when generating a response.
Key detail
Only the "When to Use" field is used to decide whether an instruction is relevant. The instruction's title and body content are not considered during selection — they are only included after an instruction has been selected.
How the Relevancy Model Thinks
The AI model that evaluates instruction relevancy is designed to be inclusive rather than exclusive. It would rather include a potentially relevant instruction than risk missing one that matters.
This means:
- Broad or generic "When to Use" descriptions will match frequently
- Semantic connections are made — "email subject for a sale" matches "marketing promotion"
- No scoring or ranking — each instruction is either selected or not
Best Practices for Writing "When to Use"
1. Be specific about the action or workflow
Too broad
When asked to help with marketing.
Better
When asked to set up or configure a marketing promotion campaign in the promotions manager.
2. Use explicit keywords as anchors
If your instruction should only activate for a specific concept, say so directly:
ONLY use when the user mentions "content scoring" or "content score." Do NOT use for general content questions.
3. Add negative conditions (exclusions)
The relevancy model respects explicit exclusions:
When asked to help with creating or designing a marketing promotion. Do NOT use for general copywriting, email subject lines, or brainstorming marketing content.
4. Distinguish between similar instructions
If you have multiple related instructions, clearly delineate boundaries:
Instruction A
When asked to write marketing email copy or subject lines for campaigns.
Instruction B
When asked to configure promotion rules, discount logic, or campaign scheduling — not for writing copy.
5. Avoid purely intent-based descriptions for narrow use cases
Intent-based (broad)
When the user needs help with sales-related tasks.
Keyword + action-based (narrow)
ONLY when the user asks to create or edit a discount code or promotion rule. Do NOT use for general questions about sales, revenue, or offers.
Common Pitfalls
| Pitfall | Why It Happens | How to Fix |
|---|---|---|
| Activates on unrelated prompts | "When to Use" is too generic | Add specific keywords and negative conditions |
| Doesn't activate when it should | "When to Use" is too narrow or uses jargon | Use natural language and include synonyms |
| Two instructions conflict | Overlapping descriptions | Add explicit boundaries and exclusions |
| Instruction always activates | Purpose like "for any general question" | Narrow scope to a specific feature or keyword |
Examples
Example 1: Too Broad → Fixed
Before (activates too often)
When asked to help with creating, planning, or designing a marketing promotion.
Problem: "Email subject for strawberry on sale" triggers this because the model links "sale" to "marketing promotion."
After (precise activation)
ONLY use for the keyword "marketing promotion." Do NOT use for other keywords like sale, offer, discount, etc.
Example 2: Anchored to a Workflow
Before
When the user asks about images.
After
When the user asks to generate, edit, or resize an image using the image generation tool. Do NOT use for questions about image file formats, image URLs, or inserting existing images.
Example 3: Using Negative Conditions
Before
When asked about customer data.
After
When asked to export, segment, or analyze customer data in the CDP. Do NOT use for questions about individual customer support tickets or account settings.
Example 4: Multiple Related Instructions
Instruction A — Content Creation
When the user asks to write, draft, or brainstorm marketing content such as email copy, social media posts, or ad text.
Instruction B — Campaign Setup
When the user asks to create, schedule, or configure a marketing campaign or automation workflow. Do NOT use for writing content or copy.
Quick Reference
| Goal | Technique | Example |
|---|---|---|
| Activate only for exact topics | Use "ONLY use for [keyword]" | ONLY use when the user mentions "A/B test" |
| Prevent false matches | Add "Do NOT use for..." | Do NOT use for general analytics questions |
| Anchor to a product feature | Name the specific feature/tool | When configuring promotion rules in the promotions manager |
| Handle synonyms | List alternative terms | When asked about content scoring, content grades, or quality scores |
| Separate related instructions | Add mutual exclusions | For campaign setup only — not for writing campaign content |
Summary
- The "When to Use" field is the only thing evaluated during instruction selection. Write it carefully.
- The system is intentionally lenient — it prefers to include instructions rather than miss them.
- Be specific: anchor to keywords, workflows, or product features.
- Use exclusions: explicitly state what the instruction should NOT match.
- Test your instructions with adjacent prompts to verify they don't trigger unexpectedly.