@simonecoelhosfo/optimizely-mcp-server/dist/resources/docs/entity-rules.md

Optimizely MCP Server for AI assistants with integrated CLI tools

# Optimizely Entity Rules and Guidelines

## 🚨 MANDATORY WORKFLOW - Entity Creation

### ALWAYS Try Direct Creation First

```
🎯 STEP 1: Try direct creation with ALL user requirements
   manage_entity_lifecycle operation=create entity_type=X entity_data={full_request}

🤖 STEP 2: Let system detect complexity and suggest templates
   Server will return template suggestions if orchestration is needed

📋 STEP 3: Use templates only when system suggests them
   Templates handle complex multi-entity operations automatically
```

### Template Mode (When Server Suggests It)

Templates are automatically suggested for:
- Flags with A/B tests, variations, variables
- Experiments with custom pages + events
- Audiences with custom attributes
- Any multi-entity orchestration

### Template Workflow (After Server Suggestion)

1. Call `get_entity_templates` with project_id and entity_type
2. Fill all `{FILL: description}` placeholders
3. Call `manage_entity_lifecycle` with `mode="template"`
4. Let orchestration handle all dependencies automatically

**📋 For comprehensive workflow details, see [EntityOrchestrator Workflows Documentation](../../docs/architecture/entity-orchestrator-workflows.md)**

### Anti-Patterns to Avoid

- ❌ Creating events/variables manually before using templates
- ❌ Manually building rulesets when template mode is available
- ❌ Modifying user-specified values without permission

## Entity Relationships

### Feature Experimentation (is_flags_enabled: true)

```
Flag
└── Rulesets (per flag + environment)
    └── Rules (targeting logic)
```

- **Rulesets**: Not standalone entities - exist as flag + environment combinations
- **Variable Definitions**: Schema/template for variables
- **Variations**: Actual variable values per variation

### Web Experimentation (is_flags_enabled: false)

```
Campaign
├── Experiments
└── Pages
```

## User Value Respect

**Critical**: Always use exactly what the user provides:
- Environment names
- Entity names
- Configuration values

If an error occurs, explain it but don't automatically retry with different values.