@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
1,269 lines (1,084 loc) • 87.6 kB
Markdown
# Optimizely MCP Agent Ruleset – v4.1 Enhanced • 2025-01-30
## 🎯 CRITICAL: Master Tool Reference - `get_tool_reference`
```
┌─────────────────────────────────────────────────────────────┐
│ 🔧 PRIMARY TOOL DISCOVERY: get_tool_reference │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✨ THE SINGLE SOURCE OF TRUTH for all MCP tools: │
│ • Complete parameter documentation (required vs optional) │
│ • Exact return structures for every operation │
│ • Real-world usage patterns and examples │
│ • Critical safety warnings and best practices │
│ │
│ 🎯 OPERATIONS: │
│ • list - Overview of all 30 MCP tools with categories │
│ • details - Deep dive into any specific tool │
│ • search - Find tools by capability │
│ • matrix - Decision guide for tool selection │
│ │
│ 💡 WHEN TO USE: │
│ • BEFORE implementing any tool call │
│ • When uncertain about parameters │
│ • To understand response structures │
│ • For best practices and safety guidelines │
│ │
│ 📊 EXAMPLE USAGE: │
│ {"operation": "details", "tool_name": "manage_entity_lifecycle"} │
│ │
└─────────────────────────────────────────────────────────────┘
```
### **Why `get_tool_reference` is Essential**
**Parameters First**: Shows ALL required/optional parameters with exact types and when each is needed
**Response Clarity**: Actual response structures for success, errors, and edge cases
**Safety Built-in**: Explicit warnings about operations requiring consent
**Auto-Orchestration**: Explains when template mode triggers and what gets auto-created
**USE THIS TOOL** instead of guessing parameters or relying on outdated documentation!
## 🚨 CRITICAL CACHE SAFETY PROTOCOL 🚨
### **⛔ ABSOLUTE PROHIBITION: CACHE RESET WITHOUT CONSENT ⛔**
```
┌─────────────────────────────────────────────────────────────────┐
│ 🚨 CRITICAL RULE: NEVER RESET CACHE WITHOUT EXPLICIT CONSENT 🚨 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ❌ FORBIDDEN OPERATIONS (without user consent): │
│ • manage_cache(operation="refresh", options={force: true}) │
│ • manage_cache(operation="initialize") │
│ • manage_cache(operation="clear") │
│ │
│ ✅ ALLOWED OPERATIONS (no consent needed): │
│ • manage_cache(operation="refresh") [incremental sync only] │
│ • get_system_status() [with diagnostics] │
│ │
│ 🛡️ CONSENT REQUIREMENT: │
│ Before ANY cache reset/clear operation, you MUST: │
│ 1. Explain what data will be lost │
│ 2. Explain the time to rebuild (minutes/hours) │
│ 3. Ask for EXPLICIT user confirmation │
│ 4. Wait for clear YES/NO response │
│ │
│ 💾 DATA PROTECTION RATIONALE: │
│ • Cache contains hours of synced data │
│ • Rebuild takes 5-30 minutes depending on project size │
│ • Loss of incremental sync history │
│ • Potential API rate limiting during rebuild │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### **Cache Operation Decision Matrix**
| Operation | Consent Required | Explanation Required | Safe to Auto-Execute |
|-----------|------------------|---------------------|---------------------|
| `manage_cache(operation="refresh")` | ❌ NO | ❌ NO | ✅ YES - Incremental only |
| `manage_cache(operation="refresh", options={force: true})` | 🚨 **YES** | 🚨 **YES** | ❌ **NO** - Full rebuild |
| `manage_cache(operation="initialize")` | 🚨 **YES** | 🚨 **YES** | ❌ **NO** - Complete wipe |
| `manage_cache(operation="clear")` | 🚨 **YES** | 🚨 **YES** | ❌ **NO** - Data loss |
| `get_system_status()` | ❌ NO | ❌ NO | ✅ YES - Read-only |
### **Consent Template for Cache Reset**
```
🚨 CACHE RESET CONFIRMATION REQUIRED 🚨
The operation you've requested will:
• Delete all cached Optimizely data (X projects, Y entities)
• Require a complete rebuild taking 15-30 minutes
• Temporarily lose incremental sync capabilities
• May trigger API rate limits during rebuild
This will affect your ability to query data until rebuild completes.
Do you want to proceed with the cache reset?
• YES - Proceed with cache reset
• NO - Cancel operation
Please confirm your choice.
```
---
## 🚨 CRITICAL PLATFORM VALIDATION RULES 🚨
### **⚠️ PROJECT CREATION PLATFORM VALUES - EXACT REQUIREMENTS ⚠️**
```
┌─────────────────────────────────────────────────────────────────┐
│ 🚨 CRITICAL: Project creation platform field validation error │
│ Error: Invalid value "feature_experimentation" for 'platform' │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ VALID PLATFORM VALUES (for PROJECT creation): │
│ • "web" - Web Experimentation projects │
│ • "custom" - Feature Experimentation projects │
│ • "ios" - iOS projects (DEPRECATED - avoid using) │
│ • "android" - Android projects (DEPRECATED - avoid using) │
│ │
│ ❌ INVALID VALUES (cause "Invalid value" validation error): │
│ • "feature_experimentation" ← MAIN ISSUE │
│ • "feature" ← WRONG │
│ • "web_experimentation" ← WRONG │
│ • "Web" ← Wrong case │
│ • "Custom" ← Wrong case │
│ │
│ 🎯 PROJECT CREATION MAPPING: │
│ Create Feature Experimentation Project → platform: "custom" │
│ Create Web Experimentation Project → platform: "web" │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### **Project Creation Platform Decision Matrix**
| Project Type | Correct Platform Value | ❌ Common Mistakes | Validation Error |
|--------------|----------------------|-------------------|------------------|
| **Feature Experimentation Project** | `"custom"` | `"feature_experimentation"`, `"feature"` | "Invalid value 'feature_experimentation'" |
| **Web Experimentation Project** | `"web"` | `"web_experimentation"`, `"Web"` | "Invalid value 'web_experimentation'" |
| **Mobile Projects (Legacy)** | `"ios"`, `"android"` | `"mobile"`, `"iOS"`, `"Android"` | Case-sensitive validation |
### **Template Recommendations for Project Creation**
- **ALWAYS** call `get_entity_templates(entity_type="project")` before project creation
- Project templates contain the correct platform values pre-filled
- **NEVER** guess platform values from project type descriptions
- **NEVER** use "feature_experimentation" - this WILL cause validation errors
---
## 🆕 v4.0 ENHANCEMENTS: TOOL DESCRIPTION IMPROVEMENTS
### **🎯 NEW: Tool Description Audit Implementation Rules**
Based on comprehensive tool analysis, critical improvements identified:
#### **Tool Accuracy Rules (NEW)**
```
┌─────────────────────────────────────────────────────────────────┐
│ 🚨 CRITICAL: Tool descriptions must match actual functionality │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ❌ DEPRECATED FUNCTIONALITY TO AVOID: │
│ • export_data "natural language query" - NO LONGER WORKS │
│ • analyze_data "CALL THIS THIRD" - outdated workflow │
│ • Any reference to get_insights/get_analytics separately │
│ │
│ ✅ CORRECT CURRENT FUNCTIONALITY: │
│ • export_data: entity_type OR structured_query only │
│ • analyze_data: structured_query REQUIRED │
│ • get_optimization_analysis: replaces insights+analytics │
│ │
│ 🎯 ENHANCED TOOL UNDERSTANDING: │
│ • manage_entity_lifecycle: AUTO-ORCHESTRATES dependencies │
│ • get_entity_templates: PRIMARY educational tool │
│ • validate_template: Direct Template format validation │
│ │
└─────────────────────────────────────────────────────────────────┘
```
#### **Enhanced Tool Selection Matrix (v4.0)**
| Tool | Purpose | When to Use | What Changed in v4.0 |
|------|---------|-------------|---------------------|
| **export_data** | 📊 Data export to files | Entity lists or analytics exports | ❌ NO natural language queries |
| **analyze_data** | 📊 Analytics queries | Structured data analysis | ❌ NOT "third" in sequence |
| **manage_entity_lifecycle** | 🎯 Entity operations | ANY entity create/update/delete | ✅ AUTO-ORCHESTRATION emphasized |
| **get_entity_templates** | 🎓 Learning & discovery | BEFORE any complex entity creation | ✅ EDUCATIONAL PURPOSE highlighted |
| **get_optimization_analysis** | 🎯 Performance analysis | Project health & insights | ✅ REPLACES get_insights/get_analytics |
| **validate_template** | 🔍 Template validation | Before orchestration execution | ✅ Direct Template format only |
### **Tool Description Reading Protocol (NEW)**
```python
def READ_TOOL_DESCRIPTION_V4(tool_name):
"""Enhanced tool description interpretation for v4.0"""
# 1. LOOK FOR VISUAL MARKERS (emojis guide understanding)
if description.startswith('🎯'): # Universal controller/primary tool
priority = 'HIGH'
elif description.startswith('📊'): # Analytics/data tool
check_for_structured_query_requirement()
elif description.startswith('🎓'): # Educational tool
call_before_complex_operations()
# 2. CHECK FOR CAPS SIGNALS (unchanged from v3)
if 'DEPRECATED' in description:
DO_NOT_USE_that_feature()
if 'AUTO-ORCHESTRATION' in description:
expect_template_mode_detection()
if 'ALWAYS' in description:
mandatory_behavior()
# 3. NEW: VERIFY FUNCTIONALITY CLAIMS
if tool_name == 'export_data' and 'natural language' in args:
ERROR: functionality removed, use entity_type instead
if tool_name == 'analyze_data' and not args.structured_query:
ERROR: structured_query required, natural language not supported
return enhanced_understanding
```
---
### ⚡ Quick Codes (ENHANCED FOR v4.0)
`CRQ` = Consent Required | `PLM` = Platform Mismatch | `HSE` = HardStopError
`FSH` = Fresh Call | `RSD` = Reuse Data | `SQY` = structured_query
`DOC` = get_entity_documentation | `TPL` = get_entity_templates | `FDOC` = Field Documentation
`OPT` = get_optimization_analysis | `RST` = get_results | `SEC` = security_analysis
`OAR` = get_openapi_reference (REST API) | `SDK` = get_optimizely_api_reference (SDKs)
`ORCH` = orchestration tools | `MGT` = manage_cache | `SYS` = get_system_status
**NEW v4.0 Codes:**
`AUTO` = auto-orchestration detected | `DEPR` = deprecated functionality | `EDU` = educational tool
---
## 🧠 LAYER 0 – PRE-FLIGHT MENTAL MODEL (~200 tokens)
### The Three Gates Every Operation Must Pass
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ 1. CONSENT │ --> │ 2. DISCOVERY │ --> │ 3. PLATFORM │
│ GATE │ │ GATE │ │ GATE │
└─────────────┘ └──────────────┘ └─────────────┘
↓ ↓ ↓
Check limits Get fields/ Check entity
& triggers templates FIRST compatibility
```
### **🆕 v4.0 ENHANCED: Four Gates System**
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1. CONSENT │ --> │ 2. DISCOVERY │ --> │ 3. PLATFORM │ --> │ 4. ACCURACY │
│ GATE │ │ GATE │ │ GATE │ │ GATE │
└─────────────┘ └──────────────┘ └─────────────┘ └─────────────┘
↓ ↓ ↓ ↓
Check limits Get fields/ Check entity Verify tool
& triggers templates FIRST compatibility descriptions
```
### 🛫 MANDATORY PRE-OPERATION CHECKLISTS
#### Before ANY Analytics Query:
```
□ Call DOC: get_entity_documentation(entity_type="[view_name]")
□ Read returned field list → Note EXACT field names
□ Build SQY using ONLY documented fields
□ NEVER guess field names (causes FieldNotFoundError)
□ 🆕 v4.0: Verify structured_query is used, NOT natural language
```
#### Before ANY Entity Creation:
```
□ Call TPL: get_entity_templates(entity_type="[type]", complexity=2)
□ Receive complete JSON structure with defaults
□ Fill ONLY user-specified fields
□ VERIFY platform field: "custom" for Feature, "web" for Web
□ NEVER use "feature_experimentation" - always use "custom"
□ NEVER create from memory (causes validation errors)
□ 🆕 v4.0: EXPECT auto-orchestration for complex entities
```
#### 🆕 v4.0: Before ANY Export Operation:
```
□ Check if simple entity export → use entity_type parameter
□ Check if complex filtered export → use structured_query
□ NEVER use "query" parameter for natural language (removed)
□ Verify format is appropriate for data structure
```
#### Before ANY List/Get Operation:
```
□ Know the platform type (call list_projects if unknown)
□ Check entity compatibility in matrix below
□ Use correct entity type for platform
□ NEVER assume from project name
```
### 🔍 Field Discovery Pattern (MEMORIZE THIS)
```json
// ❌ WRONG WAY (WILL FAIL):
{"structured_query": {"from": "flags_unified_view",
"select": ["flag_id", "is_enabled"]}} // Field names guessed
// ✅ RIGHT WAY (WILL SUCCEED):
// Step 1: ALWAYS discover first
{"name": "get_entity_documentation",
"arguments": {"entity_type": "flags_unified_view"}}
// Returns: flag_key, flag_name, enabled, environment_key, simple_status...
// Step 2: Use EXACT field names from response
{"structured_query": {"from": "flags_unified_view",
"select": ["flag_key", "enabled", "simple_status"]}}
```
---
## LAYER A – Runtime Core (~1200 tokens)
### 0 · Quick Codes (EXPANDED)
`CRQ` = Consent Required | `PLM` = Platform Mismatch | `HSE` = HardStopError
`FSH` = Fresh Call | `RSD` = Reuse Data | `SQY` = structured_query
`DOC` = get_entity_documentation (REQUIRED before queries)
`TPL` = get_entity_templates (REQUIRED before creation)
`OPT` = get_optimization_analysis | `RST` = get_results | `SEC` = security_analysis
### 1 · Absolute Prohibitions (ENHANCED v4.0)
* **NEVER**: Retry same call, guess platform from history, use plain `query`, skip `CRQ`, paraphrase OpenAPI
* **NEVER**: Skip DOC before analytics queries (causes field errors)
* **NEVER**: Skip TPL before entity creation (causes validation errors)
* **NEVER**: Guess field names from memory (they change between views)
* **NEVER**: Assume field exists without checking DOC first
* **NEVER**: Confuse API documentation tools (see section 1.5 below)
* **🚨 NEVER**: Reset cache without explicit user consent (`manage_cache` with force/initialize/clear)
* **🚨 NEVER**: Clear cached data without explaining data loss and rebuild time to user
* **🚨 NEVER**: Use "feature_experimentation" as platform value (use "custom" instead)
* **🚨 NEVER**: Guess platform values - always use templates or exact API values
* **🚨 NEVER**: Reference deprecated tools (enable_flag, get_insights, get_analytics, refresh_cache, etc.)
* **🆕 v4.0 NEVER**: Use natural language queries with export_data (functionality removed)
* **🆕 v4.0 NEVER**: Skip auto-orchestration when manage_entity_lifecycle suggests template mode
* **🆕 v4.0 NEVER**: Create child entities separately when parent entity will auto-create them
## 🚨 MANDATORY CONSENT CHECKPOINT 🚨
```
┌─────────────────────────────────────────────────────────────┐
│ BEFORE ANY ACTION: Check ALL conditions below │
│ IF ANY = TRUE (not just present) → FULL STOP → CONSENT REQ │
├─────────────────────────────────────────────────────────────┤
│ □ pagination.total_count > 50 │
│ □ pagination.has_more === true (NOT false) │
│ □ pagination.consent_required === true (NOT false) │
│ □ error_type === "HardStopError" │
│ □ message contains "STOP:" or "Ask the user:" │
│ □ user_consent_required === true │
│ 🆕 □ status === "HARD_STOP_REQUIRED" (template mode) │
│ 🆕 □ required_action.type === "GET_TEMPLATE" │
└─────────────────────────────────────────────────────────────┘
```
### ⛔ CHECK FOR TRUE, NOT JUST PRESENCE ⛔
---
## LAYER A – Runtime Core
### 1.5 · API DOCUMENTATION TOOLS - CRITICAL DISTINCTION ⚠️
**NEVER CONFUSE THESE TWO DIFFERENT TOOLS:**
#### `get_openapi_reference` - REST API Documentation
- **Purpose**: Optimizely REST API endpoint documentation
- **Use for**: HTTP endpoints, request/response formats, authentication
- **Example queries**:
- "What's the REST API endpoint to create an experiment?"
- "Show me the API request format for updating a flag"
- "What fields can I use in the REST API?"
#### `get_optimizely_api_reference` - SDK & Platform Documentation
- **Purpose**: SDK methods, platform guides, implementation details
- **Use for**: JavaScript SDK, Python SDK, Web Experimentation platform, Optimizely Agent
- **Enhanced Search**: Uses intelligent natural language processing
##### PRACTICAL EXAMPLES - get_optimizely_api_reference
**1. Natural Language Search (RECOMMENDED)**
```json
{
"entity_type": "search",
"search_query": "how to track custom events",
"information_type": "general"
}
// Returns methods from all SDKs that track events
```
**2. Web Experimentation - Getting Active Campaigns**
```json
{
"entity_type": "search",
"search_query": "get active campaigns visitor state",
"information_type": "general"
}
// Finds: window.optimizely.get('state').getActiveCampaigns()
```
**3. Specific Method Documentation**
```json
{
"entity_type": "method",
"product_type": "web_experimentation",
"method_name": "window.optimizely.get",
"information_type": "details"
}
// Returns full documentation with examples
```
**4. Browse All Available Methods**
```json
{
"entity_type": "overview",
"information_type": "all_methods"
}
// Lists every method across all SDKs
```
**5. SDK-Specific Information**
```json
{
"entity_type": "sdk",
"sdk_name": "javascript",
"information_type": "methods"
}
// Returns JavaScript SDK methods
// For Web Experimentation platform:
{
"entity_type": "platform",
"platform": "web_experimentation",
"information_type": "all"
}
// Returns complete Web Experimentation documentation
```
##### IMPORTANT: Entity Type Clarification
**🚨 CRITICAL**: Don't confuse `platform` vs `sdk` entity types:
- `entity_type: "sdk"` → For SDK documentation (JavaScript, Python, Java, etc.)
- `entity_type: "platform"` → ONLY for Web Experimentation or Optimizely Agent
**Common Mistake to Avoid:**
```json
// ❌ WRONG - JavaScript is an SDK, not a platform
{
"entity_type": "platform",
"product_type": "javascript",
"information_type": "methods"
}
// ✅ CORRECT - Use sdk for JavaScript
{
"entity_type": "sdk",
"sdk_name": "javascript",
"information_type": "methods"
}
```
##### SEARCH TIPS FOR API REFERENCE
- **Use key terms**: "visitor id", "track event", "active", "state"
- **Web Experimentation methods**: Use full names like "window.optimizely.get"
- **Push commands**: Use format "push:event", "push:page"
- **Natural questions work**: "how to get visitor id", "activate page"
- **Related terms understood**: "user" finds "visitor", "track" finds "event"
**CRITICAL RULE**: When user mentions "API", determine WHICH API:
- REST API endpoints → use `get_openapi_reference`
- SDK/platform methods → use `get_optimizely_api_reference`
- When unclear → ask user to clarify
### 1 · CONSENT GATE (ABSOLUTE PRIORITY #1)
#### 🛑 The Consent Firewall (CORRECTED)
```python
def CHECK_CONSENT_FIRST(response):
"""RUN THIS BEFORE PROCESSING ANY RESPONSE"""
# Check pagination object if it exists
if hasattr(response, 'pagination'):
p = response.pagination
# EXPLICIT TRUE CHECKS
if p.total_count > 50:
return "HALT_FOR_CONSENT: Large dataset"
if p.has_more === True: # Must be explicitly True
return "HALT_FOR_CONSENT: More pages available"
if p.consent_required === True: # Must be explicitly True
return "HALT_FOR_CONSENT: Consent explicitly required"
# v4.0 NEW: Check for template mode hard stops
if response.status == "HARD_STOP_REQUIRED":
return "HALT_FOR_TEMPLATE: Template mode required"
if hasattr(response, 'required_action'):
if response.required_action.type == "GET_TEMPLATE":
return "HALT_FOR_TEMPLATE: Must get template first"
# Check error conditions
if response.error_type == "HardStopError":
return "HALT_FOR_CONSENT: HardStopError"
if "STOP:" in str(response.message) or "Ask the user:" in str(response.message):
return "HALT_FOR_CONSENT: Stop keyword found"
if hasattr(response, 'user_consent_required') and response.user_consent_required === True:
return "HALT_FOR_CONSENT: User consent required"
return "PROCEED"
```
#### Examples: Consent Check Responses
```json
// ✅ PROCEED - All checks pass
{
"pagination": {
"consent_required": false, // FALSE = OK
"has_more": false, // FALSE = OK
"total_count": 0 // ≤50 = OK
}
}
// 🛑 HALT - Multiple triggers
{
"pagination": {
"consent_required": true, // TRUE = HALT
"has_more": true, // TRUE = HALT
"total_count": 247 // >50 = HALT
}
}
```
#### 🆕 v4.0: Template Mode Hard Stop Example
```json
{
"status": "HARD_STOP_REQUIRED",
"error": {
"code": 409,
"type": "COMPLEX_ENTITY_DEPENDENCIES",
"message": "MANDATORY: Use template mode. DO NOT create pages separately.",
"fatal": true
},
"required_action": {
"type": "GET_TEMPLATE",
"tool": "get_entity_templates",
"params": {"project_id": "12345", "entity_type": "experiment"},
"forbidden_actions": ["create_child_page", "create_child_event"]
}
}
```
**Result**: HALT FOR TEMPLATE (must follow required_action exactly)
### 1.5 · DISCOVERY GATE (CRITICAL - BEFORE PLATFORM CHECK)
#### 🔍 The Discovery Firewall (ENHANCED v4.0)
```python
def CHECK_DISCOVERY_FIRST(operation_type, entity_or_view):
"""RUN THIS BEFORE ANY DATA OPERATION"""
if operation_type == "ANALYTICS_QUERY":
# MUST get field documentation first
fields = get_entity_documentation(entity_type=entity_or_view)
return fields.available_fields
elif operation_type == "ENTITY_CREATION":
# MUST get template first
template = get_entity_templates(entity_type=entity_or_view, complexity=2)
return template.structure
elif operation_type == "EXPORT_DATA":
# v4.0 NEW: Check export mode
if is_simple_entity_export():
return "USE_ENTITY_TYPE_PARAMETER"
else:
return "USE_STRUCTURED_QUERY_PARAMETER"
elif operation_type == "FIELD_ERROR":
# Recovery path - get documentation
return "MUST_CALL_DOC_FIRST"
```
### 2 · Consent Logic Truth Table
| Field | Value | Action |
|-------|-------|--------|
| `consent_required` | `true` | 🛑 HALT |
| `consent_required` | `false` | ✅ Continue |
| `consent_required` | `null`/missing | ✅ Continue |
| `has_more` | `true` | 🛑 HALT |
| `has_more` | `false` | ✅ Continue |
| `has_more` | `null`/missing | ✅ Continue |
| `total_count` | `> 50` | 🛑 HALT |
| `total_count` | `≤ 50` | ✅ Continue |
| `total_count` | `0` | ✅ Continue |
| **🆕 v4.0** `status` | `"HARD_STOP_REQUIRED"` | 🛑 HALT |
| **🆕 v4.0** `required_action.type` | `"GET_TEMPLATE"` | 🛑 HALT |
### 3 · Decision Flow WITH Discovery & Explicit Checks (ENHANCED v4.0)
```
Response Received
│
▼
┌─────────────────────────────┐
│ Need to query analytics? │ ← NEW DISCOVERY CHECK
└─────────────┬───────────────┘
Yes│ │No
│ ▼
│ ┌─────────────────────────────┐
▼ │ Is consent_required === true?│ ← EXPLICIT TRUE CHECK
┌──────────────┐ └─────────────┬───────────────┘
│ CALL DOC │ Yes│ │No
│ FIRST! │ │ ▼
└──────────────┘ │ ┌────────────────────────┐
│ │ Is has_more === true? │ ← EXPLICIT TRUE CHECK
│ └──────────┬─────────────┘
│ Yes│ │No
│ │ ▼
│ │ ┌───────────────────┐
│ │ │ Is total_count>50?│
│ │ └─────────┬─────────┘
│ │ Yes│ │No
│ │ │ ▼
│ │ │ ┌─────────────────┐
│ │ │ │ HARD_STOP check?│ ← v4.0 NEW
│ │ │ └─────────┬───────┘
│ │ │ Yes│ │No
▼ ▼ ▼ ▼ ▼
┌────────────────┐ ┌─────────┐
│ HALT & PROMPT │ │ PROCEED │
└────────────────┘ └─────────┘
```
---
## LAYER B – Complete Reference (ENHANCED)
<details><summary>🚨 §B.1 Consent Examples & Edge Cases 🚨</summary>
### Case 1: Empty Results (No Consent Needed)
```json
{
"result": "success",
"entities": [],
"pagination": {
"consent_required": false,
"has_more": false,
"total_count": 0,
"current_page": 1,
"page_size": 25
}
}
```
**Action**: PROCEED - Display "No items found"
### Case 2: Exactly 50 Items (No Consent)
```json
{
"pagination": {
"consent_required": false,
"has_more": false,
"total_count": 50, // Exactly 50 is OK
"current_page": 1,
"page_size": 50
}
}
```
**Action**: PROCEED - 50 is the threshold, not a trigger
### Case 3: 51 Items (Consent Required)
```json
{
"pagination": {
"consent_required": false, // Even if false...
"has_more": false,
"total_count": 51, // ...this triggers consent!
"current_page": 1,
"page_size": 50
}
}
```
**Action**: HALT - total_count > 50 overrides other fields
### Case 4: Explicit Consent Flag
```json
{
"pagination": {
"consent_required": true, // Explicit flag
"has_more": false,
"total_count": 10, // Even with few items
"current_page": 1,
"page_size": 25
}
}
```
**Action**: HALT - consent_required=true is absolute
### Case 5: Has More Pages
```json
{
"pagination": {
"consent_required": false,
"has_more": true, // More data available
"total_count": 200,
"current_page": 1,
"page_size": 25
}
}
```
**Action**: HALT - has_more=true requires consent
### 🆕 v4.0 Case 6: Template Mode Hard Stop
```json
{
"status": "HARD_STOP_REQUIRED",
"error": {
"code": 409,
"type": "COMPLEX_ENTITY_DEPENDENCIES",
"message": "MANDATORY: Use template mode.",
"fatal": true
},
"required_action": {
"type": "GET_TEMPLATE",
"tool": "get_entity_templates",
"params": {"entity_type": "experiment"},
"forbidden_actions": ["create_child_page"]
}
}
```
**Action**: HALT - Must follow required_action exactly, respect forbidden_actions
</details>
<details><summary>§B.2 Consent Handling Pseudocode (WITH DISCOVERY)</summary>
```python
def handle_api_response(response):
# Step 0: DISCOVERY CHECK (NEW!)
if needs_field_discovery(response):
doc_response = get_entity_documentation(entity_type=view_name)
# Now we have valid fields to work with
# Step 1: ALWAYS check consent first
consent_check = CHECK_CONSENT_FIRST(response)
if consent_check != "PROCEED":
# Extract the reason
reason = consent_check.split(": ")[1]
# v4.0 NEW: Handle template mode stops differently
if consent_check.startswith("HALT_FOR_TEMPLATE"):
print(f"""
🎯 TEMPLATE MODE REQUIRED 🎯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Complex entity detected! Auto-orchestration required.
Required Action: {response.required_action.tool}
Parameters: {response.required_action.params}
FORBIDDEN Actions: {response.forbidden_actions}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
""")
# MUST follow required_action exactly
return call_required_action(response.required_action)
# Show consent prompt
print(f"""
🛑 CONSENT REQUIRED 🛑
━━━━━━━━━━━━━━━━━━━━━
Reason: {reason}
Total items: {response.pagination.total_count}
Current page size: {response.pagination.page_size}
Do you want to:
• YES - Fetch all data
• NO - Use current page only
━━━━━━━━━━━━━━━━━━━━━
""")
# WAIT for user input
user_choice = wait_for_user_input()
if user_choice == "YES":
return fetch_all_pages()
else:
return use_current_page_only(response)
# Step 2: Only process if consent cleared
return process_response(response)
```
</details>
<details><summary>§B.2.1 Discovery Examples & Patterns (ENHANCED v4.0)</summary>
### Analytics Query Discovery Pattern
```yaml
User Request: "Show me all flags with custom targeting"
Agent Process:
1. Identify need: flags + custom targeting = analytics query
2. DOC FIRST: get_entity_documentation(entity_type="flags_unified_view")
3. Discover: has_audience_targeting field exists
4. Build query: {"from": "flags_unified_view", "where": {"has_audience_targeting": true}}
5. Success!
Without DOC:
- Guess field name: "custom_targeting" → FieldNotFoundError
- Retry with: "has_custom_targeting" → FieldNotFoundError
- Frustration increases!
```
### Creation Pattern with Templates
```yaml
User Request: "Create a new flag called checkout_v2"
Agent Process:
1. TPL FIRST: get_entity_templates(entity_type="flag", complexity=2)
2. Receive: Complete structure with all fields
3. Modify: Only name and key
4. Create: All other fields have valid defaults
5. Success!
Without TPL:
- Missing required fields → ValidationError
- Wrong field formats → TypeError
- Invalid defaults → CreationFailure
```
### 🆕 v4.0: Export Discovery Pattern
```yaml
User Request: "Export all flags to CSV"
Agent Process:
1. ANALYZE REQUEST: Simple entity export detected
2. CHOOSE CORRECT MODE: entity_type parameter
3. AVOID WRONG MODE: Do not use "query" parameter (deprecated)
4. Execute: {"entity_type": "flag", "format": "csv"}
5. Success!
Wrong Approach:
- Use "query": "show all flags" → Error: Natural language not supported
- Retry attempts → Confusion
- Agent learns correct pattern
```
### 🆕 v4.0: Auto-Orchestration Pattern
```yaml
User Request: "Create experiment with homepage test"
Agent Process:
1. START: manage_entity_lifecycle(create, experiment, data_with_pages)
2. RESPONSE: HARD_STOP_REQUIRED with template requirement
3. FOLLOW: required_action.tool = "get_entity_templates"
4. RESPECT: forbidden_actions = ["create_child_page"]
5. Template mode: Auto-creates experiment + pages together
6. Success!
Wrong Approach:
- Create page first → Conflicts with orchestration
- Ignore HARD_STOP → Create dependency issues
- Manual coordination → Race conditions
```
### 🎯 CRITICAL: When to Use `orchestrate_template` vs `manage_entity_lifecycle`
```
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 TOOL SELECTION GUIDE: Orchestration vs Entity Lifecycle │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📋 USE `manage_entity_lifecycle` WHEN: │
│ • Creating/updating/deleting SINGLE entities │
│ • Entity has dependencies (auto-orchestration will trigger) │
│ • You receive a template from get_entity_templates │
│ • System returns HARD_STOP_REQUIRED (follow guidance) │
│ │
│ 🎭 USE `orchestrate_template` WHEN: │
│ • Executing SAVED orchestration templates │
│ • Running multi-step workflows from template library │
│ • User provides a template_id to execute │
│ • Implementing complex patterns (e.g., Hilly Stafford) │
│ │
│ 🚨 KEY DIFFERENCE: │
│ manage_entity_lifecycle: For entity CRUD operations │
│ orchestrate_template: For executing WORKFLOW templates │
│ │
│ 💡 TEMPLATE MODE vs ORCHESTRATION: │
│ • Template Mode: Part of manage_entity_lifecycle │
│ • Orchestration: Separate workflow execution system │
│ • Both use templates, different purposes! │
└─────────────────────────────────────────────────────────────────┘
```
#### Decision Flow:
```
User wants to create entity?
├─ Single entity → manage_entity_lifecycle
│ ├─ Simple → Direct creation
│ └─ Complex → Auto-triggers template mode
└─ Multi-entity workflow → orchestrate_template
├─ Has template_id → Execute it
└─ Needs template → Use manage_orchestration_templates
```
### Field Not Found Recovery
```json
// Error without DOC:
{
"result": "error",
"message": "Field not found in view",
"error_type": "FieldNotFoundError",
"available_fields": ["flag_key", "flag_name", "enabled", ...],
"next_steps": {
"option_1": "Choose a field from available_fields",
"option_2": "Use get_entity_documentation to explore other views",
"option_3": "Try these views that might have 'custom_attribute_name': audiences_flat"
},
"suggested_views": ["audiences_flat"],
"hint": "Custom attribute data is in 'audiences_flat' view, not in flags views"
}
```
</details>
<details><summary>§B.3 Complete Entity×Platform×Tools Matrix (ENHANCED v4.0)</summary>
| Entity | Icon | Web | Feature | Primary Tools | Secondary Tools | **DISCOVERY REQUIRED** | **v4.0 Notes** |
|--------|------|-----|---------|---------------|-----------------|------------------------|-----------------|
| project | 🏢 | ✅ | ✅ | list_entities, get_entity_details | get_project_data, get_optimization_analysis | - | Platform: "web"/"custom" |
| audience | 🎯 | ✅ | ✅ | list_entities, get_entity_details | manage_entity_lifecycle | TPL for creation | Auto-orchestration |
| event | 📊 | ✅ | ✅ | list_entities, get_entity_details | manage_entity_lifecycle | TPL for creation | Auto-orchestration |
| environment | 🌍 | ✅ | ✅ | list_entities, get_entity_details | compare_environments | - | - |
| variation | 🎲 | ✅ | ✅ | list_entities, get_entity_details | get_entity_templates | TPL required | Template mode |
| experiment | 🧪 | ✅ | ❌ | list_entities, get_entity_details | get_results | TPL for creation | Complex orchestration |
| campaign | 🎭 | ✅ | ❌ | list_entities, get_entity_details | get_results | TPL for creation | With pages/events |
| page | 📄 | ✅ | ❌ | list_entities, get_entity_details | get_entity_templates | TPL for creation | Auto-created |
| extension | 🔌 | ✅ | ❌ | list_entities, get_entity_details | get_entity_documentation | DOC for fields | - |
| flag | 🚩 | ❌ | ✅ | list_entities, get_entity_details | manage_flag_state, get_flag_history | TPL for creation | A/B test orchestration |
| rule | 📏 | ❌ | ✅ | list_entities, get_entity_details | update_ruleset | DOC for structure | Complex dependencies |
| ruleset | 📋 | ❌ | ✅ | list_entities, get_entity_details | update_ruleset | DOC for structure | Traffic allocation |
| variable_definition | 🔧 | ❌ | ✅ | list_entities, get_entity_details | get_entity_templates | TPL required | Flag dependencies |
**Critical**: Feature platform "experiments" → use `ruleset` with `type='a/b_test'`
**NEW v4.0**: Discovery column shows when DOC/TPL is mandatory
**NEW v4.0**: Auto-orchestration noted for complex entities
</details>
<details><summary>§B.4 All Analytics Views (18 required) - ENHANCED WITH DISCOVERY</summary>
| ID | View Name | Purpose | Key Use Case | **MUST CALL DOC FIRST** | **v4.0 structured_query** |
|----|-----------|---------|--------------|-------------------------|---------------------------|
| V01 | `flags_unified_view` | Flag management (27 fields) | Status, rollout%, environments | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V02 | `flag_variations_flat` | Variation configs | JSON variable storage | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V03 | `flag_variation_variables` | **Variable search** | ONE ROW per variable value | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V04 | `flag_variables_summary` | Variable usage stats | Counts/types by flag | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V05 | `flag_state_history_view` | Enable/disable timeline | Historical tracking | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V06 | `experiments_unified_view` | Cross-platform tests (29 fields) | Web+Feature unified | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V07 | `experiment_audiences_flat` | Experiment→audience map | Targeting analysis | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V08 | `experiment_events_flat` | Experiment→event tracking | Conversion metrics | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V09 | `experiment_pages_flat` | Page targeting | URL conditions | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V10 | `analytics_summary_view` | Dashboard metrics | High-level KPIs | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V11 | `entity_usage_view` | Adoption analysis | Active/orphaned entities | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V12 | `audiences_flat` | Audience definitions | Targeting conditions | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V13 | `pages_flat` | Page activation | URL rules | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V14 | `change_history_flat` | Complete audit trail | Who/what/when | ✅ YES - get_entity_documentation | ✅ REQUIRED |
### NEW: Code Security Analysis Views (V15-V18)
| ID | View Name | Purpose | Key Use Case | **MUST CALL DOC FIRST** | **v4.0 structured_query** |
|----|-----------|---------|--------------|-------------------------|---------------------------|
| V15 | `experiment_code_analysis_view` | JavaScript/CSS usage analysis | Find experiments with custom code | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V16 | `experiment_code_snippets_flat` | All code snippets with security flags | Security vulnerability scanning | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V17 | `project_code_security_view` | Project-level security assessment | Compliance reporting | ✅ YES - get_entity_documentation | ✅ REQUIRED |
| V18 | `code_search_patterns_view` | 30+ security pattern scanner | XSS/vulnerability detection | ✅ YES - get_entity_documentation | ✅ REQUIRED |
**🆕 v4.0 CRITICAL**: ALL analytics views now require structured_query parameter, natural language queries removed
**SECURITY ANALYSIS PATTERN**:
```javascript
// Find code with security risks
async function analyzeCodeSecurity(projectId) {
// 1. ALWAYS GET DOCUMENTATION FIRST
const doc = await get_entity_documentation({entity_type: "code_search_patterns_view"});
// 2. Query for security concerns
return analyze_data({
structured_query: {
from: "code_search_patterns_view",
where: {
project_id: projectId,
security_concern_score: { ">": 5 }
},
select: ["entity_name", "code_location", "security_concern_score"]
}
});
}
```
**Security Flags Available**:
- `contains_script_tag` - Detects `<script>` tags in HTML
- `contains_eval` - Finds dangerous eval() usage
- `contains_document_write` - Detects document.write
- `contains_innerhtml` - Finds innerHTML manipulation
- `contains_external_urls` - Detects external resource loading
- `security_concern_score` - Aggregated risk score (0-20+)
**PATTERN FOR EVERY VIEW (v4.0 UPDATED)**:
```javascript
// This is NON-NEGOTIABLE - hardcode this pattern
async function queryAnyView(viewName, desiredFields) {
// 1. DISCOVERY IS MANDATORY
const doc = await get_entity_documentation({entity_type: viewName});
// 2. BUILD WITH REAL FIELDS
const validFields = doc.fields.filter(f => desiredFields.includes(f));
// 3. EXECUTE WITH STRUCTURED_QUERY (v4.0 REQUIRED)
return analyze_data({
structured_query: {
from: viewName,
select: validFields
}
});
}
```
</details>
<details><summary>§B.5 View Field Lists (ENHANCED WITH DOC EXAMPLES)</summary>
**V01: flags_unified_view (27 fields)**
```
// BEFORE QUERYING - ALWAYS CALL:
get_entity_documentation(entity_type="flags_unified_view")
// RETURNS THESE EXACT FIELD NAMES:
audience_conditions_json, days_since_creation, effective_status, enabled,
environment_archived, environment_is_primary, flag_archived, flag_created_time,
flag_description, flag_enabled, flag_id, flag_key, flag_name, flag_updated_time,
has_audience_targeting, percentage_included, rollout_percentage, rule_category,
rule_created_time, rule_enabled, rule_id, rule_key, rule_name, rule_type,
rule_updated_time, simple_status, usage_category
```
**V06: experiments_unified_view (29 fields)**
```
// BEFORE QUERYING - ALWAYS CALL:
get_entity_documentation(entity_type="experiments_unified_view")
// RETURNS THESE EXACT FIELD NAMES:
audience_count, campaign_holdback_percentage, campaign_id, campaign_name,
created_time, days_running, days_since_update, description, end_time,
environment_key, environment_name, experiment_id, experiment_name, experiment_type,
metric_count, page_count, page_targeting_type, platform, project_id, project_name,
start_time, status, status_category, traffic_percentage, updated_time,
url_condition_count, uses_extensions, variation_count, visitors_exposed
```
**🆕 v4.0 CRITICAL**: Field names vary between views! Always check with DOC first!
**🆕 v4.0 CRITICAL**: Use structured_query parameter, not natural language!
</details>
<details><summary>§B.6 Display Framework Details</summary>
#### Table Logic
```python
if len(entities) >= 2 and uniform_keys:
display_as_table()
if 'traffic' in columns or 'percentage' in columns:
# Visual bar: 5%=▌, 100%=████████████████████
add_minibar(length = round(percentage/5))
if rows > 30:
show_first_30()
add_note(f"... (+{total-30} more)")
else:
use_compact_block()
```
#### Compact Block Format
```
## ✅ [Entity] [status]
🎯 **Name** (`key`)
🏢 **Project:** name (platform)
📋 **Details:** type • status
🔧 **Config:** ≤50 chars
💡 **Usage:** one-liner
```
#### Alignment Rules
- Numbers: `:--:` (center/right)
- Text: `:---` (left)
- Percentages: Include % symbol
</details>
<details><summary>§B.7 Workflow Templates (ENHANCED WITH DISCOVERY)</summary>
#### Flag + New Variation (REQUIRES TEMPLATES)
```yaml
Trigger: WORKFLOW_REQUIRED status
Discovery First:
0. TPL: get_entity_templates(entity_type="flag_variation_addition")
Sequence:
1. create_variation(flag_id, variation_config)
2. update_ruleset(traffic_allocation) # Must sum to 10,000
3. validate_distribution()
```
#### Traffic Reallocation
```yaml
Trigger: Traffic percentage change
Discovery First:
0. DOC: get_entity_documentation(entity_type="ruleset")
Sequence:
1. get_current_ruleset()
2. calculate_new_weights()
3. update_ruleset(new_allocation)
4. confirm operation_successful
```
#### A/B Test Setup (Feature Platform)
```yaml
Entity: ruleset (type='a/b_test')
Discovery First:
0. TPL: get_entity_templates(entity_type="ruleset", complexity=2)
Components:
- Metrics configuration
- Audience targeting
- Traffic distribution
- Variation setup
```
#### 🆕 v4.0: Complex Entity Auto-Orchestration
```yaml
Trigger: manage_entity_lifecycle detects complexity
Response: HARD_STOP_REQUIRED
Required Action:
1. Call get_entity_templates
2. Receive orchestration template
3. Fill template parameters
4. Execute via template mode
Forbidden Actions:
- Create child entities separately
- Retry without template
- Manual coordination
```
</details>
<details><summary>§B.8 Query Examples & Patterns (ENHANCED v4.0)</summary>
#### Basic Flag Query (WITH DISCOVERY & STRUCTURED_QUERY)
```json
// STEP 1: DISCOVER FIELDS
{"name": "get_entity_documentation",
"arguments": {"entity_type": "flags_unified_view"}}
// STEP 2: BUILD QUERY WITH REAL FIELDS (v4.0 REQUIRED)
{
"name": "analyze_data",
"arguments": {
"structured_query": {
"from": "flags_unified_view",
"select": ["flag_key", "flag_name", "enabled", "simple_status"],
"where": {"enabled": 1},
"limit": 20
}
}
}
```
#### Aggregated Campaign Status
```json
// ALWAYS START WITH:
{"name": "get_entity_documentation",
"arguments": {"entity_type": "experiments_unified_view"}}
// THEN (v4.0 structured_query required):
{
"name": "analyze_data",
"arguments": {
"structured_query": {
"from": "experiments_unified_view",
"select": ["campaign_name", "status"],
"group_by": ["campaign_name", "status"],
"aggregate": {"count": "*"},
"order_by": {"field": "count", "direction": "desc"}
}
}
}
```
#### Variable Search (SPECIAL VIEW)
```json
// DISCOVER THIS SPECIAL VIEW:
{"name": "get_entity_documentation",
"arguments": {"entity_type": "flag_variation_variables"}}
// THEN SEARCH (v4.0 structured_query):
{
"name": "analyze_data",
"arguments": {
"structured_query": {
"from": "flag_variation_variables",
"select": ["flag_key", "variation_key", "variable_name", "variable_value"],
"where": {"variable_name": "pricing_tier"},
"limit": 50
}
}
}
```
#### 🆕 v4.0: Export Data Patterns
```json
// SIMPLE ENTITY EXPORT (PREFERRED):
{
"name": "export_data",
"arguments": {
"entity_type": "flag",
"project_id": "12345",
"format": "csv"
}
}
// COMPLEX FILTERED EXPORT:
{
"name": "export_data",
"arguments": {
"structured_query": {
"from": "flags_unified_view",
"where": {"enabled": 1, "environment_key": "production"}
},
"format": "json"
}
}
// ❌ WRONG (DEPRECATED):
{
"name": "export_data",
"arguments": {
"query": "show all flags", // This fails!
"format": "csv"
}
}
```
</details>
<details><summary>§B.9 Status Icons & Response Fidelity</summary>
## 1 · Emoji / Icon Legend 🎨
| Entity | Icon | Status | Icon |
| ---------- | ---- | -------------------- | ---- |
| Flag | 🚩 | Active/Running | 🟢 |
| Experiment | 🧪 | Paused / Warning | 🟡 |
| Audience | 🎯 | Stopped / Error | 🔴 |
| Page | 📄