@simonecoelhosfo/optimizely-mcp-server/dist/resources/docs/anti-patterns.md

Optimizely MCP Server for AI assistants with integrated CLI tools

# Optimizely MCP Anti-Patterns Guide

## Critical Rule: Never Extract Nested Entity Data

### The Golden Rule
**NEVER extract nested entity data from parent objects. Always use dedicated entity API endpoints.**

## Common Anti-Patterns and Corrections

### Variable Definitions
❌ **WRONG**: "Looking at flag data, I can see the variable definitions are..."  
✅ **CORRECT**: "Let me get the variable definitions using the proper entity call: `list_entities variable_definition project_id=X filters={"flag_key": "FLAG_KEY"}`"

### Variations
❌ **WRONG**: "From the flag details, the variations are..."  
✅ **CORRECT**: "Let me list the variations properly: `list_entities variation project_id=X filters={"flag_key": "FLAG_KEY"}`"

### Rules
❌ **WRONG**: "I can extract the rules from the ruleset data..."  
✅ **CORRECT**: "Let me get the rules using: `list_entities rule project_id=X filters={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}`"

### Rulesets
❌ **WRONG**: "The ruleset is embedded in the flag data..."  
✅ **CORRECT**: "Let me get the ruleset: `get_entity_details ruleset "" project_id=X options={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}`"

## Entity Decision Tree

When a user asks for specific entities, follow this decision tree:

```
User asks for variable_definitions?
→ list_entities variable_definition project_id=X filters={"flag_key": "FLAG_KEY"}
  (Returns SCHEMA/TEMPLATE - not actual values)

User asks for variations?
→ list_entities variation project_id=X filters={"flag_key": "FLAG_KEY"}
  (Returns actual variable VALUES)

User asks for rules?
→ list_entities rule project_id=X filters={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}

User asks for rulesets?
→ get_entity_details ruleset "" project_id=X options={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}

User asks for flag overview?
→ get_entity_details flag FLAG_KEY project_id=X
  (Embedded data OK for overview only)
```

## Understanding Variable Definitions vs Variables

### Variable Definitions
- **What they are**: Schema/template that DEFINES what variables can exist in a flag
- **Contains**: Variable key, data type (string, boolean, integer), default value, description
- **Purpose**: Defines the structure - like a database schema
- **Analogy**: Like a form template that defines what fields exist

### Variables in Variations
- **What they are**: Actual VALUES assigned to the defined variables in each variation
- **Contains**: Specific values for each variable defined in variable_definitions
- **Purpose**: The actual data users see when they get a flag variation
- **Analogy**: Like a filled-out form with actual values

### Example Relationship
```json
// Variable Definition
{"key": "button_color", "type": "string", "default_value": "blue"}

// Variation Control
{"button_color": "blue"}

// Variation Treatment
{"button_color": "red"}
```

**Explanation**: Definition says "button_color can be a string, defaults to blue". Variations set actual values.

## Before Responding Checklist

Before providing any response about entities:

1. ✅ Did I check if user asked for a specific entity type?
2. ✅ Am I about to extract data instead of using proper entity calls?
3. ✅ Should I use list_entities instead of embedded data?
4. ✅ Did I provide flag_key filter for flag-scoped entities?

## Validation Before Response

🚨 **STOP CHECK**: Am I about to say "Looking at flag data" or "From the flag details"? 
If YES → STOP and use proper entity calls!

## Consequences of Violations

Using embedded data instead of proper entity calls:
- Violates entity independence
- Provides incomplete results
- May return stale or incorrect data
- Breaks the MCP contract of using proper tools

## Platform-Specific Anti-Patterns

### Feature Experimentation
- ❌ DON'T extract variations from experiment.variations property
- ❌ DON'T extract rules from experiment.rules property
- ✅ DO use dedicated entity endpoints with proper filters

### Web Experimentation
- ❌ DON'T extract variations from experiment.variations property
- ❌ DON'T extract pages from experiment.pages property
- ✅ DO use dedicated entity endpoints with proper filters

Remember: Both platforms have entities called "experiments" but they work differently. Always check the project platform first!