snow-flow 8.1.6 → 8.3.0

package/CLAUDE.md

@@ -1,1204 +1,1053 @@
-# Snow-Flow Configuration & Best Practices
+# Snow-Flow ServiceNow Development Framework
 
-## 🚨 CRITICAL: PREVENT INFINITE TASK LOOPS
+## ⚡ QUICK START - READ THIS FIRST!
 
-**NEVER spawn multiple agents for the same task type!**
+| What You Want | ❌ WRONG (will fail!) | ✅ CORRECT (works!) |
+|---------------|----------------------|---------------------|
+| Create UI Page | `node dist/index.js mcp execute ...` | `await snow_create_ui_page({...})` |
+| Create Workspace | `npx snow-flow-mcp-client ...` | `await snow_create_complete_workspace({...})` |
+| Query Incidents | `snow-flow mcp execute ...` | `await snow_query_incidents({...})` |
+| Any MCP Tool | Bash/CLI commands | Direct function call |
 
-**❌ INFINITE LOOP (PROHIBITED):**
-```
-Task("UI Builder Tools Tester", "Test UI Builder tools");
-Task("UI Builder Tools Tester", "Test UI Builder tools");  // ← DUPLICATE AGENT TYPE!
-Task("Workspace Tools Tester", "Test workspace tools");
-Task("Workspace Tools Tester", "Test workspace tools");  // ← CAUSES INFINITE LOOP!
-
-// This pattern causes MCP server spam:
-// • Task(UI Builder Tools Tester) → snow_validate_uib_page_structure (repeated 100x)
-// • Task(Workspace Tools Tester) → snow_execute_script_with_output (repeated 100x)
-```
+**🎯 MCP tools are JavaScript functions - call them directly! NO bash/node/npx needed!**
 
-**✅ CORRECT (Single Agent):**
-```
-// UNIQUE agent names prevent loops:
-Task("workspace-architect", "Create ONE UX workspace for IT support using snow_create_complete_workspace. Store all sys_ids in Memory.");
-Task("ui-specialist", "Design UI components AFTER workspace-architect completes. Use Memory to get workspace sys_ids.");
-Task("testing-validator", "Test workspace functionality AFTER ui-specialist completes. No duplicate testing!");
-
-// NEVER use generic names like:
-// Task("Tester", ...) - TOO GENERIC, CAUSES LOOPS!
-// Task("UI Builder Tools Tester", ...) - EXACTLY what caused the infinite loop!
+---
+
+## 🚨 CRITICAL: HOW MCP TOOLS WORK IN OPENCODE
+
+**MCP tools are AUTOMATICALLY AVAILABLE - NO bash/npx/node needed!**
+
+```javascript
+// ✅ CORRECT - MCP tools are available directly:
+await snow_create_ui_page({
+  name: "incident_dashboard",
+  html: "<div>...</div>"
+});
+
+await snow_create_complete_workspace({
+  workspace_name: "IT Support",
+  tables: ["incident", "task"]
+});
 ```
 
-**🎯 Anti-Loop Rules:**
-1. **ONE agent per task type maximum**
-2. **Specific agent instructions** (not generic descriptions)
-3. **Wait for completion** before spawning additional agents  
-4. **Check Memory for existing work** before spawning
-5. **NO duplicate Task() calls** with same objective
+## 🚫 FORBIDDEN BASH PATTERNS - NEVER DO THIS!
 
----
+**❌ THESE COMMANDS DO NOT EXIST AND WILL ALWAYS FAIL:**
+
+```bash
+# ❌ WRONG - This file does NOT exist in user's project!
+node dist/index.js mcp execute --server "servicenow-platform-dev" --tool "snow_create_ui_page"
+# ERROR: Cannot find module 'dist/index.js'
 
-This document provides comprehensive instructions for Snow-Flow, an advanced ServiceNow development and orchestration framework powered by Claude AI.
+# ❌ WRONG - This package does NOT exist!
+npx snow-flow-mcp-client servicenow-unified snow_create_ui_page {...}
+# ERROR: 404 Not Found
 
-## Table of Contents
-1. [Core Philosophy](#core-philosophy)
-2. [Fundamental Rules](#fundamental-rules)
-3. [ServiceNow Development Standards](#servicenow-development-standards)
-4. [MCP Server Capabilities](#mcp-server-capabilities)
-5. [Debugging Best Practices](#debugging-best-practices)
-6. [Command Reference](#command-reference)
-7. [Workflow Guidelines](#workflow-guidelines)
+# ❌ WRONG - MCP tools are NOT CLI commands!
+snow-flow mcp execute --tool snow_create_ui_page
+# ERROR: No such command
 
-## CRITICAL: Widget Debugging Must Use Local Sync
+# ❌ WRONG - You cannot "run" MCP tools via bash!
+cd project && node snow_create_ui_page.js
+# ERROR: Wrong approach entirely!
+```
 
-### \ud83d\udd34 When User Reports Widget Issues, ALWAYS Use `snow_pull_artifact` FIRST!
+**🚨 WHY THESE FAIL:**
+- MCP tools are **functions**, NOT CLI commands
+- They are loaded by OpenCode/Claude Code automatically
+- No `dist/` directory exists in user's project
+- No CLI wrapper exists for MCP tools
 
-**Common scenarios that REQUIRE Local Sync:**
-- "Widget skips questions" \u2192 `snow_pull_artifact`
-- "Form doesn't submit properly" \u2192 `snow_pull_artifact`
-- "Data not displaying" \u2192 `snow_pull_artifact`
-- "Button doesn't work" \u2192 `snow_pull_artifact`
-- "Debug this widget" \u2192 `snow_pull_artifact`
-- "Fix widget issue" \u2192 `snow_pull_artifact`
+**✅ CORRECT WAY (the ONLY way that works):**
 
-**DO NOT use `snow_query_table` for widget debugging!** It will hit token limits and you can't use native search/edit tools.
+```javascript
+// Just call the function directly - it's already available!
+const result = await snow_create_ui_page({
+  name: "incident_management",
+  title: "Incident Management",
+  html: "...",
+  processing_script: "..."
+});
+```
 
-## Core Philosophy
+**🎯 KEY RULE:**
+**IF you think you need bash/node/npx to call an MCP tool, you are WRONG! MCP tools are JavaScript functions - call them directly!**
 
-### The Prime Directive: Use Dedicated Tools First, Then Verify
+## 🚨 ABSOLUTE RULES - NO EXCEPTIONS
 
-Snow-Flow operates on "**Tools-First, Evidence-Based**" development. Always use the highest-level, most specific tool available before falling back to generic approaches.
+### 🔴 RULE #0: MCP TOOLS FIRST - NEVER USE LOCAL APPROACHES!
 
-**Cardinal Rules:**
-1. **🔍 Tool Discovery First** - Always search for dedicated MCP tools before using scripts
-2. **🎯 Use Highest-Level Tool** - Prefer domain-specific tools over generic database operations  
-3. **📊 Problem Categorization** - High-level business operations → dedicated tools, low-level data → scripts
-4. **✅ Verify, Don't Assume** - Test before declaring something broken
-5. **🔧 Fix Only Confirmed Issues** - Respect existing configurations
+**❌ WRONG APPROACH (FORBIDDEN):**
+- Writing local scripts to "test something first"
+- Using background scripts for complex operations instead of MCP tools
+- Creating files locally "to prepare before deployment"
+- Building things locally then deploying to ServiceNow
+- Using generic queries when specific MCP tools exist
 
-### The Tools-First Approach
+**✅ CORRECT APPROACH (MANDATORY):**
+- **ALWAYS search for MCP tools FIRST** before doing anything
+- **Use dedicated MCP tools** for every ServiceNow operation
+- **Create directly in ServiceNow** via MCP tools, never locally first
+- **Dedicated tool > Background script** ALWAYS
 
-**✅ CORRECT Decision Process:**
+**Examples:**
 ```javascript
-// Step 1: User Request Analysis
-User: "Create agent workspace for IT support"
-
-// Step 2: Tool Discovery FIRST  
-Search Snow-Flow MCP tools for:
-- "create_workspace" → FOUND: snow_create_workspace
-- "workspace_create" → FOUND: snow_create_workspace  
-- "agent_workspace" → FOUND: snow_create_workspace
-
-// Step 3: Use Dedicated Tool
-const result = await snow_create_workspace({
-  name: "IT Support Workspace",
-  tables: ["incident", "task", "sys_user"],
-  description: "Agent workspace for IT support team"
+// ❌ WRONG: Using background script for workspace creation
+snow_execute_background_script({
+  script: "var gr = new GlideRecord('sys_ux_app_config')..."
 });
 
-// Step 4: Only if dedicated tool fails → verify with scripts
-if (!result.success && result.plugin_required) {
-  // Now use verification script to check plugin availability
-}
+// ✅ CORRECT: Use dedicated MCP tool
+snow_create_complete_workspace({
+  workspace_name: "IT Support Workspace",
+  tables: ["incident", "task"]
+});
+
+// ❌ WRONG: Generic query when specific tool exists
+snow_query_table({ table: 'sp_widget', query: 'sys_id=...' });
+
+// ✅ CORRECT: Use dedicated widget tool
+snow_pull_artifact({ sys_id: 'widget_sys_id' });
 ```
 
-**❌ WRONG Approach (Anti-Pattern):**
+**MCP Tool Discovery Process:**
+1. **Search**: "Does a tool exist for [task]?" (e.g., snow_create_workspace, snow_deploy_widget)
+2. **Check category**: deployment, operations, ui-builder, workspace, automation
+3. **Use dedicated tool**: ALWAYS prefer specific tools over generic ones
+4. **Background scripts**: ONLY for verification, NEVER for development
+
+### 🔴 RULE #1: UPDATE SET WORKFLOW - MANDATORY FOR ALL DEVELOPMENT!
+
+**🚨 CRITICAL: EVERY development task MUST follow this workflow:**
+
 ```javascript
-// DON'T DO THIS: Jumping straight to scripts for business operations
-User: "Create agent workspace"
-→ snow_execute_script_with_output({ script: "var gr = new GlideRecord('sys_aw_master_config')..." })
+// STEP 1: ALWAYS create/ensure active Update Set FIRST (before ANY development)
+const updateSet = await snow_create_update_set({
+  name: "Feature: [Descriptive Name]",  // e.g., "Feature: Incident Dashboard Widget"
+  description: "Complete description of changes",
+  application: "global"  // or specific app scope
+});
+
+// STEP 2: Ensure it's active (Snow-Flow auto-sets as current in ServiceNow!)
+await snow_ensure_active_update_set({
+  sys_id: updateSet.sys_id
+});
 
-// This bypasses all our error handling, plugin detection, and business logic!
+// STEP 3: NOW start development - all changes auto-tracked
+await snow_deploy({
+  type: 'widget',
+  config: { name: 'incident_dashboard', ... }
+});
+
+// STEP 4: Complete Update Set when done
+await snow_complete_update_set({
+  sys_id: updateSet.sys_id,
+  state: 'complete'
+});
+```
+
+**❌ FORBIDDEN WORKFLOW:**
+- Starting development without creating Update Set first
+- Creating artifacts then trying to "add them to Update Set later"
+- Assuming changes are being tracked (they're not without active Update Set!)
+- Working across multiple Update Sets for single feature
+
+**✅ MANDATORY WORKFLOW:**
+1. **CREATE Update Set** (descriptive name: "Feature: X" or "Fix: Y")
+2. **ACTIVATE Update Set** (snow_ensure_active_update_set)
+3. **DEVELOP** (all changes auto-tracked in active Update Set)
+4. **COMPLETE Update Set** (mark as complete when done)
+
+**Update Set Best Practices:**
+- **One feature = One Update Set** (clear scope)
+- **Descriptive names**: "Feature: Incident Auto-Assignment" not "Changes"
+- **Complete description**: What, why, affected tables/components
+- **Always check current**: Use snow_sync_current_update_set if unsure
+
+### 🔴 RULE #2: Widget Debugging MUST Use Local Sync!
+
+**When user reports ANY widget issue, ALWAYS use:**
 ```
+snow_pull_artifact({ sys_id: 'widget_sys_id' })
+```
+
+**NEVER use snow_query_table for widgets!** It will hit token limits and you can't use native tools.
+
+**Common scenarios requiring snow_pull_artifact:**
+- "Widget skips questions" → snow_pull_artifact
+- "Form doesn't submit" → snow_pull_artifact
+- "Data not displaying" → snow_pull_artifact
+- "Button doesn't work" → snow_pull_artifact
+- "Debug this widget" → snow_pull_artifact
+- "Fix widget issue" → snow_pull_artifact
+- Widget script > 1000 chars → snow_pull_artifact
+
+### Rule #3: NO MOCK DATA - EVERYTHING REAL & COMPLETE
+**FORBIDDEN:** Mock data, placeholders, TODOs, stub implementations, test values, simulations, "this would normally...", partial implementations.
+**REQUIRED:** Complete, production-ready, fully functional code. Take time to implement EVERYTHING properly. Real integrations, comprehensive error handling, full validation.
+
+### Rule #4: ES5 ONLY - ServiceNow Rhino Engine
+**NEVER USE:** const/let, arrow functions =>, template literals `${}`, destructuring, for...of, default parameters, classes
+**ALWAYS USE:** var, function(){}, string concatenation +, traditional for loops, typeof checks
+
+### Rule #5: VERIFY FIRST - Never Assume
+Test before claiming broken. Check resources exist. Validate configurations. Evidence-based fixes only.
+
+## 🔍 TOOL DISCOVERY DECISION TREE - USE THIS EVERY TIME!
+
+**Before doing ANYTHING, follow this decision tree:**
+
+### Step 1: What is the user asking for?
+
+| User Request | Task Category | Go to Step 2 |
+|--------------|---------------|--------------|
+| "Create workspace/UI/widget/rule/etc." | CREATE NEW | → Create Decision |
+| "Fix/update/modify existing X" | UPDATE EXISTING | → Update Decision |
+| "Debug/check/test X" | DEBUG/VERIFY | → Debug Decision |
+| "Show/list/find X" | QUERY DATA | → Query Decision |
+
+### Step 2: Find the Right Tool
+
+**CREATE NEW Decision:**
+- User wants: "Create workspace for IT agents"
+  - Category: Workspace (UX Framework)
+  - Tool: `snow_create_complete_workspace`
+  - REMEMBER: Create Update Set FIRST!
+
+- User wants: "Create business rule"
+  - Category: Platform Development
+  - Tool: `snow_create_business_rule`
+  - REMEMBER: Create Update Set FIRST!
+
+- User wants: "Create widget"
+  - Category: Deployment
+  - Tool: `snow_deploy` (type: 'widget')
+  - REMEMBER: Create Update Set FIRST!
+
+- User wants: "Create UI Builder page"
+  - Category: UI Builder
+  - Tool: `snow_create_uib_page`
+  - REMEMBER: Create Update Set FIRST!
+
+**UPDATE EXISTING Decision:**
+- Updating: Widget
+  - Is it debugging? YES: `snow_pull_artifact` (local sync)
+  - Simple field update? NO: `snow_update` (type: 'widget')
+
+- Updating: Any other artifact
+  - Tool: `snow_update` or `snow_edit_artifact`
+  - REMEMBER: Ensure Update Set is active!
+
+**DEBUG/VERIFY Decision:**
+- Debugging: Widget not working
+  - ALWAYS: `snow_pull_artifact` (get all files locally)
+  - NEVER: `snow_query_table` (token limits!)
+
+- Debugging: Script/rule not working
+  - Tool: `snow_execute_script_with_output` (test the code)
 
-### Problem Categorization Guide
+- Verifying: Table/field exists
+  - Tool: `snow_execute_script_with_output` (check with GlideRecord)
 
-**🎯 High-Level Business Operations → Dedicated Tools:**
-- "Create workspace" → `snow_create_workspace`
-- "Create UI Builder page" → `snow_create_uib_page`  
-- "Deploy widget" → `snow_deploy`
-- "Create flow" → Flow Designer tools
-- "Add component to page" → `snow_add_uib_page_element`
+**QUERY DATA Decision:**
+- Querying: Widget data
+  - NEVER: `snow_query_table` (use `snow_pull_artifact` instead!)
 
-**🔧 Low-Level Data Operations → Scripts OK:**
-- "Check if field exists in table"
-- "Verify property value"  
-- "Test custom query"
-- "Debug specific record"
+- Querying: Table data (incidents, users, etc.)
+  - Tool: `snow_query_table` or specific tools (`snow_query_incidents`)
 
-**🚨 Decision Tree:**
-1. **User says "Create X"** → Search for `snow_create_X` or `snow_X_create` tools FIRST
-2. **User says "Configure Y"** → Search for `snow_configure_Y` tools FIRST  
-3. **User says "Custom script for Z"** → Scripts are appropriate
-4. **User says "Check/verify/test"** → Scripts for verification are good
+- Querying: Multiple tables
+  - Tool: `snow_batch_api` (80% faster!)
 
-**🎯 Workspace Feature Development:**
-- **"Create workspace list"** → Use `snow_create_uib_component` (list component) + `snow_create_uib_data_broker`
-- **"Add workspace tab"** → Use `snow_create_uib_page` + `snow_add_uib_page_element`
-- **"Configure workspace panel"** → Use `snow_create_uib_component` + `snow_add_uib_page_element`
+### Step 3: MANDATORY - Update Set Check!
 
-### The Verification-First Approach
+**🚨 BEFORE calling ANY development tool, ask yourself:**
 
+- ✅ Did I create an Update Set? If NO: STOP! Create one first!
+- ✅ Is the Update Set active? If NO: Call `snow_ensure_active_update_set`!
+- ✅ Ready to develop? NOW you can call the tool!
+
+**The Update Set Mantra (repeat before EVERY development task):**
+1. CREATE Update Set (`snow_create_update_set`)
+2. ACTIVATE Update Set (`snow_ensure_active_update_set`)
+3. DEVELOP (now all changes are tracked!)
+4. COMPLETE Update Set (`snow_complete_update_set`)
+
+---
+
+## 📋 MCP SERVERS & TOOLS (18 Servers, 200+ Tools)
+
+### 1. **servicenow-local-development** 🔧 Widget/Artifact Sync [USE THIS FOR WIDGETS!]
+```
+snow_pull_artifact - Pull ANY artifact to local files (ALWAYS use for widgets!)
+snow_push_artifact - Push local changes back to ServiceNow  
+snow_cleanup_artifacts - Clean local artifact cache
+snow_get_sync_status - Check artifact sync status
+snow_list_local_artifacts - List all pulled artifacts
+```
+**⚠️ CRITICAL: For ANY widget work, use snow_pull_artifact FIRST, not snow_query_table!**
+
+### 2. **servicenow-deployment** 🚀 Complete Deployment System
+```
+snow_deploy - Create NEW artifacts (widgets, flows, scripts, pages)
+snow_update - UPDATE existing artifacts directly
+snow_validate_deployment - Validate before deploy
+snow_rollback_deployment - Rollback failed deployments
+snow_preview_widget - Preview widget rendering
+snow_widget_test - Test widget functionality
+snow_deployment_history - View deployment history
+snow_check_widget_coherence - Validate HTML/Client/Server communication
+```
+
+### 3. **servicenow-operations** 📊 Core Operations
+```
+snow_query_table - Universal table query (NOT for widgets - use snow_pull_artifact!)
+snow_query_incidents - Query and analyze incidents
+snow_analyze_incident - AI-powered incident analysis
+snow_auto_resolve_incident - Automated resolution
+snow_cmdb_search - Configuration database search
+snow_user_lookup - Find users and groups
+snow_operational_metrics - Performance metrics
+snow_knowledge_search - Search knowledge base
+snow_catalog_item_manager - Manage service catalog
+```
+
+### 4. **servicenow-automation** ⚙️ Scripts & Automation
+```
+snow_execute_background_script - Run ES5 scripts (autoConfirm available)
+snow_execute_script_with_output - Execute with output capture
+snow_execute_script_sync - Synchronous execution
+snow_get_script_output - Retrieve script results
+snow_schedule_job - Create scheduled jobs
+snow_create_event - Trigger system events
+snow_get_logs - Access system logs
+snow_test_rest_connection - Test REST endpoints
+snow_trace_execution - Performance tracing
+```
+
+### 5. **servicenow-platform-development** 🏗️ Development Artifacts
+```
+snow_create_ui_page - Create UI pages
+snow_create_script_include - Reusable scripts
+snow_create_business_rule - Business rules
+snow_create_client_script - Client-side scripts
+snow_create_ui_policy - UI policies
+snow_create_ui_action - UI actions
+snow_create_acl - Access controls
+snow_create_ui_macro - UI macros
+```
+
+### 6. **servicenow-integration** 🔌 Integrations
+```
+snow_create_rest_message - REST integrations
+snow_create_soap_message - SOAP integrations
+snow_create_transform_map - Data transformation
+snow_create_import_set - Import management
+snow_test_web_service - Test services
+snow_configure_email - Email configuration
+snow_create_data_source - Data sources
+```
+
+### 7. **servicenow-system-properties** ⚙️ Properties
+```
+snow_property_get - Get property value
+snow_property_set - Set property value
+snow_property_list - List by pattern
+snow_property_bulk_update - Bulk operations
+snow_property_export/import - Export/Import JSON
+snow_property_validate - Validate properties
+```
+
+### 8. **servicenow-update-set** 📦 Change Management [MANDATORY FOR ALL DEVELOPMENT!]
+```
+snow_create_update_set - Create new update set (ALWAYS FIRST STEP!)
+snow_ensure_active_update_set - Auto-create and activate (sets as current in ServiceNow!)
+snow_sync_current_update_set - Sync Snow-Flow with user's current Update Set
+snow_complete_update_set - Mark complete when done
+snow_export_update_set - Export as XML for deployment
+snow_preview_update_set - Preview changes before committing
+snow_list_update_sets - List all update sets
+snow_get_update_set_changes - View tracked changes
+```
+**🚨 CRITICAL:** EVERY development task MUST start with snow_create_update_set or snow_ensure_active_update_set!
+
+**Complete Workflow Example:**
 ```javascript
-// Before claiming anything doesn't work or exist:
-// Step 1: Test the actual implementation
-const verify = await snow_execute_script_with_output({
-  script: `/* Test the exact code or resource */`
+// 1. CREATE UPDATE SET (before ANY development!)
+const updateSet = await snow_create_update_set({
+  name: "Feature: Incident Auto-Assignment",
+  description: "Implements automatic incident assignment based on category and location",
+  application: "global"
+});
+
+// 2. ENSURE IT'S ACTIVE (Snow-Flow auto-sets as current in ServiceNow!)
+await snow_ensure_active_update_set({ sys_id: updateSet.sys_id });
+
+// 3. NOW DEVELOP (all changes auto-tracked)
+await snow_create_business_rule({
+  name: "Auto-assign incidents",
+  table: "incident",
+  when: "before",
+  active: true,
+  script: "var assignment = new IncidentAssignment(); assignment.autoAssign(current);"
 });
 
-// Step 2: Check if resources exist
-const tableCheck = await snow_discover_table_fields({
-  table_name: 'potentially_custom_table'
+await snow_deploy({
+  type: 'widget',
+  config: { name: 'assignment_dashboard', ... }
 });
 
-// Step 3: Validate configurations
-const propertyCheck = await snow_property_manager({
-  action: 'get',
-  name: 'system.property'
+// 4. COMPLETE UPDATE SET
+await snow_complete_update_set({
+  sys_id: updateSet.sys_id,
+  state: 'complete'
 });
+```
+
+### 9. **servicenow-development-assistant** 🤖 AI Assistant
+```
+snow_find_artifact - Find any artifact by name/type
+snow_edit_artifact - Edit existing artifacts
+snow_analyze_artifact - Analyze dependencies
+snow_comprehensive_search - Deep search all tables
+snow_analyze_requirements - Requirement analysis
+snow_generate_code - Pattern-based generation
+snow_optimize_script - Performance optimization
+```
+
+### 10. **servicenow-security-compliance** 🛡️ Security
+```
+snow_create_security_policy - Security policies
+snow_audit_compliance - SOX/GDPR/HIPAA audit
+snow_scan_vulnerabilities - Vulnerability scan
+snow_assess_risk - Risk assessment
+snow_review_access_control - ACL review
+snow_encrypt_field - Field encryption
+snow_audit_trail_analysis - Audit analysis
+```
+
+### 11. **servicenow-reporting-analytics** 📈 Reporting
+```
+snow_create_report - Create reports
+snow_create_dashboard - Build dashboards
+snow_define_kpi - Define KPIs
+snow_schedule_report - Schedule delivery
+snow_analyze_data_quality - Data quality
+snow_create_pa_widget - Performance analytics
+```
+
+### 12. **servicenow-machine-learning** 🧠 Native PI + Local ML
+
+**🚨 TWO COMPLETELY DIFFERENT ML APPROACHES!**
+
+**🏢 Native ServiceNow Predictive Intelligence (NEW! v7.4.0):**
+- Runs INSIDE ServiceNow (requires PI license)
+- Production-ready, auto-retrain, enterprise ML
+- Tools: snow_create_pi_solution, snow_train_pi_solution, snow_monitor_pi_training, snow_activate_pi_solution
+- **ALWAYS ask:** "Do you have a ServiceNow Predictive Intelligence license?"
+
+**💻 Local TensorFlow.js ML (Experimental):**
+- Runs locally on dev machine (FREE, no license)
+- Development/testing only, NOT for production
+- Tools: ml_train_incident_classifier, ml_predict_change_risk, ml_detect_anomalies
+
+**📋 Decision Matrix:**
+| User Says | Has PI License? | Recommend |
+|-----------|----------------|-----------|
+| "Create incident predictor" | ✅ Yes | Native PI: snow_create_pi_solution |
+| "Create incident predictor" | ❌ No | Local TensorFlow.js: ml_train_incident_classifier |
+| "Production ML solution" | ✅ Yes | Native PI (always) |
+| "Production ML solution" | ❌ No | STOP: Explain PI license required |
+| "Test/experiment with ML" | Either | Can use local TensorFlow.js |
+
+**🚨 CRITICAL: ALWAYS ask about PI license before recommending ML tools!**
+
+```
+# Native PI Tools (Production):
+snow_create_pi_solution - Create PI solution definition
+snow_train_pi_solution - Train model in ServiceNow (10-30 min)
+snow_monitor_pi_training - Monitor training progress/metrics
+snow_activate_pi_solution - Activate for production use
+snow_list_pi_solutions - List all PI solutions
+ml_predictive_intelligence - Make predictions (requires trained PI solution)
+
+# Local ML Tools (Dev/Testing Only):
+ml_train_incident_classifier - Train LSTM classifier locally
+ml_predict_change_risk - Local risk prediction
+ml_detect_anomalies - Local anomaly detection
+ml_forecast_incidents - Local time series forecast
+ml_cluster_similar - Local similarity clustering
+ml_performance_analytics - Native PA ML
+```
+
+### 13. **servicenow-change-virtualagent-pa** 🔄 Change & Virtual Agent
+```
+snow_create_change_request - Change requests
+snow_assess_change_risk - Risk assessment
+snow_create_nlu_model - NLU models
+snow_train_virtual_agent - Train VA
+snow_configure_conversation - VA conversations
+snow_analyze_pa_trends - Performance trends
+```
 
-// Step 4: Only then make informed decisions
+### 14. **servicenow-cmdb-event-hr-csm-devops** 🏢 Enterprise
+```
+snow_manage_ci - Configuration items
+snow_correlate_events - Event correlation
+snow_manage_hr_case - HR cases
+snow_csm_project - Customer projects
+snow_devops_pipeline - CI/CD pipelines
+snow_manage_cmdb_relationships - CI relationships
 ```
 
-### 🔄 CRITICAL: Sync User Modifications Before Working
+### 15. **servicenow-knowledge-catalog** 📚 Knowledge & Catalog (v3.6.10 Corrected!)
+```
+snow_create_knowledge_article - KB articles
+snow_create_catalog_item - Catalog items
+snow_create_catalog_variable - Variable sets
+snow_create_catalog_ui_policy - CORRECTED: Creates in 2 tables (conditions as string, actions as records)
+snow_order_catalog_item - Order catalog items
+snow_discover_catalogs - Discover available catalogs
+```
+**✅ Corrected UI Policy (v3.6.10):** Conditions stored as query string in catalog_conditions field. Actions created in catalog_ui_policy_action table. Based on actual ServiceNow structure!
+
+### 16. **servicenow-flow-workspace-mobile** 📱 Modern UX + UI Builder
+```
+# Flow Designer Tools
+snow_list_flows - List Flow Designer flows
+snow_execute_flow - Execute flows programmatically  
+snow_get_flow_execution_status - Monitor flow status
+snow_get_flow_execution_history - Flow execution history
+snow_get_flow_details - Flow configuration details
+snow_import_flow_from_xml - Import flows from XML
+
+# Agent Workspace Tools  
+snow_create_workspace - Create agent workspace configurations
+snow_create_workspace_tab - Add custom workspace tabs
+snow_create_contextual_panel - Add contextual side panels
+snow_discover_workspaces - Find all workspace configurations
+
+# Mobile App Tools
+snow_configure_mobile_app - Configure mobile applications
+snow_send_push_notification - Send push notifications  
+snow_configure_offline_sync - Setup offline synchronization
+
+# 🆕 COMPLETE UI BUILDER INTEGRATION (15 NEW TOOLS!)
+# Page Management (sys_ux_page)
+snow_create_uib_page - Create UI Builder pages with routing
+snow_update_uib_page - Update page configuration
+snow_delete_uib_page - Delete pages with dependency validation
+snow_discover_uib_pages - Find all UI Builder pages
+
+# Component Library (sys_ux_lib_*)  
+snow_create_uib_component - Create custom UI components
+snow_update_uib_component - Update component source & schema
+snow_discover_uib_components - Browse component library
+snow_clone_uib_component - Clone & modify existing components
+
+# Data Integration (sys_ux_data_broker)
+snow_create_uib_data_broker - Connect ServiceNow data sources
+snow_configure_uib_data_broker - Update queries & caching
+
+# Layout Management (sys_ux_page_element)
+snow_add_uib_page_element - Add components to pages
+snow_update_uib_page_element - Update component properties
+snow_remove_uib_page_element - Remove elements with validation
+
+# Advanced UI Builder Features
+snow_create_uib_page_registry - Configure URL routing
+snow_discover_uib_routes - Find all page routes
+snow_create_uib_client_script - Add client-side scripts
+snow_create_uib_client_state - Manage page state  
+snow_create_uib_event - Create custom events
+snow_analyze_uib_page_performance - Performance analysis
+snow_validate_uib_page_structure - Structure validation
+snow_discover_uib_page_usage - Usage analytics
+```
 
-**When a user mentions they've modified an artifact directly in ServiceNow, ALWAYS fetch the latest version first!**
+### 17. **servicenow-advanced-features** 🎯 Advanced
+```
+snow_performance_optimization - Optimize instance
+snow_batch_operations - Bulk processing
+snow_instance_scan - Health check
+snow_dependency_analysis - Dependencies
+snow_code_search - Search all code
+```
 
-If a user says any of these:
-- "I've updated the widget in ServiceNow"
-- "I made some changes to the flow"
-- "I modified the script"
-- "I adjusted the configuration"
-- "Ik heb het zelf aangepast" (Dutch: I adjusted it myself)
+### 18. **snow-flow** 🎛️ Orchestration
+```
+swarm_init - Initialize agent swarms
+agent_spawn - Create specialized agents
+task_orchestrate - Complex task coordination
+memory_search - Search persistent memory
+neural_train - Train neural networks
+```
 
-**YOU MUST:**
+## 🔄 Critical Workflows - Quick Reference
 
-1. **Immediately fetch the current version from ServiceNow:**
+### Widget Work: ALWAYS Local Sync!
 ```javascript
-// For any artifact the user has modified
-const currentVersion = await snow_query_table({
-  table: 'artifact_table_name',
-  query: `sys_id=${artifact_sys_id}`,
-  fields: ['*'],  // Get all fields
-  limit: 1
-});
+// ✅ CORRECT
+await snow_pull_artifact({ sys_id: 'widget_sys_id' });
+// ... edit locally ...
+await snow_push_artifact({ sys_id: 'widget_sys_id' });
+
+// ❌ WRONG - Token limits!
+await snow_query_table({ table: 'sp_widget', ... });
+```
+
+### Development: ALWAYS Update Set First!
+```javascript
+// ✅ CORRECT - Update Set workflow
+const updateSet = await snow_create_update_set({ name: "Feature: X" });
+await snow_ensure_active_update_set({ sys_id: updateSet.sys_id });
+// ... develop ...
+await snow_complete_update_set({ sys_id: updateSet.sys_id });
+
+// ❌ WRONG - No Update Set tracking!
+await snow_create_business_rule({ ... }); // Changes NOT tracked!
+```
 
-// Or for widgets specifically
-const widgetData = await snow_query_table({
-  table: 'sp_widget',
-  query: `sys_id=${widget_sys_id}`,
-  fields: ['name', 'template', 'client_script', 'script', 'css', 'option_schema'],
-  limit: 1
+### Verification: Use Scripts for Testing Only
+```javascript
+// ✅ For verification/testing
+await snow_execute_script_with_output({
+  script: `var gr = new GlideRecord('incident'); gs.info('Exists: ' + gr.isValid());`
 });
 
-// Or use snow_get_by_sysid for comprehensive retrieval
-const artifact = await snow_get_by_sysid({
-  table: 'table_name',
-  sys_id: 'the_sys_id'
+// ❌ NOT for development!
+await snow_execute_background_script({
+  script: `var gr = new GlideRecord('sp_widget'); gr.initialize(); ...` // WRONG!
 });
 ```
 
-2. **Analyze the user's modifications:**
-   - Review what they changed
-   - Understand their intent
-   - Preserve their modifications
+## 🚨 THE UNIVERSAL WORKFLOW - MEMORIZE THIS!
+
+**Every task follows this pattern:**
+
+1. **📦 UPDATE SET FIRST** - `snow_create_update_set` → `snow_ensure_active_update_set`
+2. **🔍 FIND RIGHT TOOL** - Use Tool Discovery Decision Tree above
+3. **🛠️ USE MCP TOOL** - Call the dedicated tool (NEVER background scripts for development!)
+4. **✅ TEST/VERIFY** - Use `snow_execute_script_with_output` for verification only
+5. **✔️ COMPLETE UPDATE SET** - `snow_complete_update_set` when done
+
+**Special Case - Widget Debugging:**
+1. UPDATE SET FIRST
+2. `snow_pull_artifact` (get all files locally)
+3. Edit with native tools
+4. `snow_push_artifact` (push back to ServiceNow)
+5. COMPLETE UPDATE SET
+
+## 🎯 The 4 Absolute Rules
+
+1. **🔴 UPDATE SETS ALWAYS FIRST** - No development without Update Set tracking!
+2. **🔴 MCP TOOLS ONLY** - Use dedicated tools, NOT background scripts for development
+3. **🔴 NO MOCK DATA** - Everything real, complete, production-ready (no TODOs, no placeholders)
+4. **🔴 ES5 JAVASCRIPT ONLY** - var, function(){}, string concatenation (ServiceNow Rhino engine)
+
+## 📊 Quick Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Widget doesn't work | `snow_pull_artifact` + debug locally |
+| Forgot Update Set | `snow_create_update_set` → `snow_ensure_active_update_set` |
+| Syntax error in script | Check ES5! No const/let/arrows/template literals |
+| Widget too large | Use `snow_pull_artifact`, NOT `snow_query_table` |
+| Need to test code | `snow_execute_script_with_output` (verification only!) |
+
+---
+
+**🚨 FINAL REMINDER: Update Sets are MANDATORY. MCP Tools are AUTOMATICALLY available. NO Mock Data. ES5 Only.**
+---
+
+## 🆕 V8.2.0: OPTIMIZED MCP TOOLS & BREAKING CHANGES
+
+### 📊 What Changed in v8.2.0
+
+**Major Optimizations:**
+1. ✅ **Description Optimization**: All 409 tools have concise, token-efficient descriptions
+2. ✅ **Metadata Addition**: Every tool now has category, subcategory, use_cases, complexity, and frequency metadata
+3. ✅ **Tool Merging**: Reduced redundancy by merging related tools
+
+**Breaking Changes:**
+- **Update Set Tools**: 9 tools merged → 3 tools (6 tools removed)
+
+### 🔄 Update Set Tools Migration Guide
 
-3. **Build upon their changes:**
-   - Don't overwrite their work
-   - Integrate new features with their modifications
-   - Maintain their code style and patterns
+**OLD (REMOVED in v8.2.0):**
+```javascript
+// These tools NO LONGER EXIST:
+snow_update_set_create({ name, description })
+snow_update_set_switch({ update_set_id })
+snow_update_set_complete({ update_set_id })
+snow_update_set_export({ update_set_id })
+snow_update_set_preview({ update_set_id })
+snow_update_set_add_artifact({ update_set_id, artifact_sys_id })
+snow_update_set_current()
+snow_update_set_list({ state, limit })
+```
 
-4. **Inform the user:**
-   - Acknowledge that you've fetched their latest changes
-   - Summarize what modifications you found
-   - Explain how you'll build upon their work
+**NEW (v8.2.0+):**
+```javascript
+// Unified management tool:
+snow_update_set_manage({
+  action: 'create',  // or 'switch', 'complete', 'export', 'preview', 'add_artifact'
+  name: 'My Update Set',
+  description: 'Description',
+  auto_switch: true
+})
+
+// Unified query tool:
+snow_update_set_query({
+  action: 'current'  // or 'list'
+  // For list: state, limit, order_by
+})
+
+// Still available (complex logic):
+snow_ensure_active_update_set({ name, description })
+```
+
+**Migration Examples:**
 
-**Example Workflow:**
 ```javascript
-// User: "I've updated the widget to add a loading spinner"
-// Snow-Flow response:
-
-// 1. Fetch current version
-const widget = await snow_query_table({
-  table: 'sp_widget',
-  query: `sys_id=${widgetSysId}`,
-  fields: ['*'],
-  limit: 1
+// OLD: Create and switch
+await snow_update_set_create({ name: 'STORY-123', description: 'Add widget' });
+
+// NEW: Same functionality
+await snow_update_set_manage({
+  action: 'create',
+  name: 'STORY-123',
+  description: 'Add widget',
+  auto_switch: true  // default
 });
 
-// 2. Analyze changes
-console.log("✅ Fetched your latest widget version from ServiceNow");
-console.log("📝 I see you've added a loading spinner in the template");
+// OLD: Get current Update Set
+await snow_update_set_current();
+
+// NEW: Same functionality
+await snow_update_set_query({ action: 'current' });
+
+// OLD: List Update Sets
+await snow_update_set_list({ state: 'in progress', limit: 10 });
 
-// 3. Work with the updated version
-// ... make additional changes based on user's modifications ...
+// NEW: Same functionality
+await snow_update_set_query({
+  action: 'list',
+  state: 'in progress',
+  limit: 10
+});
 ```
 
-**Why This Matters:**
-- User modifications are not tracked locally
-- Working with outdated versions causes conflicts
-- User's work could be lost if not synced
-- Builds trust by respecting user's contributions
-- Ensures coherent development flow
-
-## Fundamental Rules
-
-### Rule 1: ES5 JavaScript Only in ServiceNow
-
-ServiceNow uses the Rhino JavaScript engine which supports only ES5. Modern JavaScript syntax will fail.
-
-**Never Use:**
-- `const` or `let` - use `var`
-- Arrow functions `() => {}` - use `function() {}`
-- Template literals `` `${var}` `` - use string concatenation
-- Destructuring `{a, b} = obj` - use explicit property access
-- `for...of` loops - use traditional `for` loops
-- Default parameters - use `typeof` checks
-- `async/await` - use callbacks or GlideAjax
-- `enum` - use object literals with constants instead
-- Classes - use function constructors with prototypes
-- Spread operator `...` - use Array methods or loops
-- Array methods like `map`, `filter`, `reduce` - use for loops
-
-**Always Use:**
-```javascript
-// ES5 compatible code
-var name = 'value';
-function processData() {
-  return 'result';
-}
-var message = 'Hello ' + userName;
-for (var i = 0; i < array.length; i++) {
-  var item = array[i];
-}
+---
+
+## 🎯 CATEGORY-AWARE TOOL SELECTION (v8.2.0+)
+
+Every MCP tool now has metadata to help you choose the right tool faster!
 
-// Instead of enum, use object literals:
-var Status = {
-  PENDING: 'pending',
-  ACTIVE: 'active',
-  COMPLETED: 'completed'
-};
+### Tool Metadata Structure
 
-// Instead of class, use function constructor:
-function MyClass(name) {
-  this.name = name;
+```javascript
+{
+  category: 'core-operations',      // Main category
+  subcategory: 'query',             // Specific subcategory
+  use_cases: ['data-retrieval'],    // What it's used for
+  complexity: 'beginner',           // beginner | intermediate | advanced | expert
+  frequency: 'very-high'            // very-high | high | medium | low
 }
-MyClass.prototype.getName = function() {
-  return this.name;
-};
 ```
 
-### Rule 2: Use Local Sync for Widget Debugging - NOT snow_query_table!
+### 📁 Tool Categories
+
+**1. core-operations**
+   - Subcategories: query, crud, properties, discovery
+   - Frequency: very-high
+   - Examples: snow_query_table, snow_create_record, snow_update_record
+
+**2. development**
+   - Subcategories: update-sets, deployment, local-sync, platform
+   - Frequency: very-high
+   - Examples: snow_update_set_manage, snow_deploy, snow_pull_artifact
+
+**3. ui-frameworks**
+   - Subcategories: ui-builder, workspace, service-portal
+   - Frequency: high
+   - Examples: snow_create_uib_page, snow_create_complete_workspace, snow_deploy
+
+**4. automation**
+   - Subcategories: script-execution, flow-designer, scheduling
+   - Frequency: high
+   - Examples: snow_execute_script_with_output, snow_execute_flow, snow_schedule_job
+
+**5. integration**
+   - Subcategories: rest-soap, transform-maps, import-export
+   - Frequency: medium
+   - Examples: snow_create_rest_message, snow_create_transform_map
+
+**6. itsm**
+   - Subcategories: incident, change, problem, knowledge, catalog
+   - Frequency: high
+   - Examples: snow_query_incidents, snow_create_change_request, snow_search_knowledge
+
+**7. cmdb**
+   - Subcategories: ci-management, discovery, relationships
+   - Frequency: medium
+   - Examples: snow_create_ci, snow_run_discovery, snow_create_ci_relationship
+
+**8. ml-analytics**
+   - Subcategories: predictive-intelligence, performance-analytics, machine-learning
+   - Frequency: medium
+   - Examples: snow_create_pi_solution, snow_train_pi_solution, snow_create_pa_indicator
+
+**9. advanced**
+   - Subcategories: specialized, batch-operations, process-mining
+   - Frequency: low-medium
+   - Examples: snow_batch_api, snow_analyze_query, snow_discover_process
+
+---
+
+## 🔍 QUICK TOOL FINDER BY USE CASE
 
-**CRITICAL: When debugging widgets, ALWAYS use `snow_pull_artifact` first!**
+### Creating Workspaces for Agents
+
+**Category**: ui-frameworks → workspace
+**Primary Tool**: `snow_create_complete_workspace`
+**Related Tools**: `snow_create_uib_page`, `snow_add_uib_page_element`
 
 ```javascript
-// ✅ CORRECT - Use Local Sync for widget debugging
-snow_pull_artifact({ 
-  sys_id: 'widget_sys_id',
-  table: 'sp_widget' 
+// Complete workspace in ONE call:
+await snow_create_complete_workspace({
+  workspace_name: "IT Support Workspace",
+  description: "Agent workspace for IT support team",
+  tables: ["incident", "task", "problem"]
 });
-// Now use Claude Code native search, multi-file edit, etc.
+```
 
-// ❌ WRONG - Don't use snow_query_table for debugging widgets
-snow_query_table({ 
-  table: 'sp_widget',
-  query: 'sys_id=...',
-  fields: ['template', 'script', 'client_script'] 
+### Widget Development & Debugging
+
+**Category**: ui-frameworks → service-portal, development → local-sync
+**Primary Tools**: `snow_deploy`, `snow_pull_artifact`, `snow_push_artifact`
+
+```javascript
+// CRITICAL: Use Local Sync for widget debugging!
+await snow_pull_artifact({
+  sys_id: 'widget_sys_id',
+  table: 'sp_widget'
 });
-// This hits token limits and can't use native tools!
+// Now edit locally with native tools
+await snow_push_artifact({ sys_id: 'widget_sys_id' });
 ```
 
-**Why Local Sync for Widget Debugging:**
-- **No token limits** - Handle widgets of ANY size
-- **Native search** - Find issues across all files instantly
-- **Multi-file view** - See relationships between components
-- **Better debugging** - Trace data flow, find missing methods
-- **Coherence checking** - Validate all parts work together
+### UI Builder Page Development
+
+**Category**: ui-frameworks → ui-builder
+**Primary Tools**: `snow_create_uib_page`, `snow_add_uib_page_element`, `snow_create_uib_data_broker`
+
+```javascript
+// Create page
+const page = await snow_create_uib_page({
+  name: "incident_dashboard",
+  title: "Incident Dashboard"
+});
 
-**Widget Debugging Workflow:**
-1. User reports issue → `snow_pull_artifact`
-2. Search for error patterns across files
-3. Fix using multi-file edit
-4. Validate coherence → `snow_validate_artifact_coherence`
-5. Push fixes back → `snow_push_artifact`
+// Add components
+await snow_add_uib_page_element({
+  page_sys_id: page.sys_id,
+  component_id: "list-component",
+  config: { table: "incident" }
+});
+```
 
-### Rule 3: Background Scripts for Verification Only
+### Update Set Management
 
-Background scripts provide immediate feedback but should NOT be used for widget updates. Use them for verification:
+**Category**: development → update-sets
+**Primary Tools**: `snow_update_set_manage`, `snow_update_set_query`, `snow_ensure_active_update_set`
 
 ```javascript
-// Use for verification and testing
-const verify = await snow_execute_script_with_output({
-  script: `/* Test code */`
+// ALWAYS create Update Set FIRST:
+await snow_update_set_manage({
+  action: 'create',
+  name: 'STORY-456',
+  description: 'Add workspace features',
+  auto_switch: true
 });
-```
 
-### Rule 4: Widget Coherence - Critical Client-Server Communication
+// Make changes...
 
-ServiceNow widgets MUST have perfect communication between client and server scripts. This is not optional - widgets fail when these components don't talk to each other correctly.
+// Complete when done:
+await snow_update_set_manage({
+  action: 'complete',
+  update_set_id: 'sys_id_here'
+});
+```
 
-**IMPORTANT: Use Local Sync Instead of Query for Large Widgets**
+### Script Execution & Testing
 
-When you see "exceeds maximum allowed tokens" errors, don't try to fetch fields separately with `snow_query_table`. Use Local Sync instead:
+**Category**: automation → script-execution
+**Primary Tool**: `snow_execute_script_with_output`
 
 ```javascript
-// ❌ WRONG - Don't do this when debugging:
-snow_query_table({ table: 'sp_widget', fields: ['name'] });
-snow_query_table({ table: 'sp_widget', fields: ['script'] });
-snow_query_table({ table: 'sp_widget', fields: ['client_script'] });
-// This is inefficient and can't use native tools!
-
-// ✅ CORRECT - Use Local Sync:
-snow_pull_artifact({ 
-  sys_id: '01d01d6983176a502a7ea130ceaad376' 
+// ES5 ONLY! Test scripts:
+await snow_execute_script_with_output({
+  script: `
+    var gr = new GlideRecord('incident');
+    gr.query();
+    gs.info('Total incidents: ' + gr.getRowCount());
+  `
 });
-// All files available locally with NO token limits!
 ```
 
-**Local Sync Benefits:**
-- Handles widgets of ANY size automatically
-- All files available for native tool usage
-- Maintains relationships between components
-- Enables powerful search and refactoring
-
-**The Three-Way Contract:**
-
-**Server Script Must:**
-- Initialize all `data` properties that HTML will reference
-- Handle every `input.action` that client sends
-- Return data in the format client expects
-
-**Client Script Must:**
-- Implement every method that HTML calls via `ng-click`
-- Use `c.server.get({action: 'name'})` for server communication
-- Update `c.data` when server responds
-
-**HTML Template Must:**
-- Only reference `data` properties that server provides
-- Only call methods that client implements
-- Use correct Angular directives and bindings
-
-**Critical Communication Points:**
-
-1. **Server → Client Data Flow**
-   - Server sets `data.property`
-   - Client receives via `c.data.property`
-   - HTML displays with `{{data.property}}`
-
-2. **Client → Server Requests**
-   - Client sends `c.server.get({action: 'name'})`
-   - Server receives via `input.action`
-   - Server processes and returns updated `data`
-
-3. **HTML → Client Method Calls**
-   - HTML has `ng-click="methodName()"`
-   - Client must have `$scope.methodName = function()`
-   - Method typically calls server with `c.server.get()`
-
-**Common Failures to Avoid:**
-- Action name mismatches between client and server
-- Method name mismatches between HTML and client  
-- Property name mismatches between server and HTML
-- Missing handlers for client requests
-- Orphaned data properties or methods
-
-**Coherence Validation Checklist:**
-- [ ] Every `data.property` in server is used in HTML/client
-- [ ] Every `ng-click` in HTML has matching `$scope.method` in client
-- [ ] Every `c.server.get({action})` in client has matching `if(input.action)` in server
-- [ ] Data flows correctly: Server → HTML → Client → Server
-- [ ] No orphaned methods or unused data properties
-
-### Rule 5: Evidence-Based Debugging
-
-Follow this systematic approach for all debugging:
-
-1. **Reproduce** - Run the exact failing code
-2. **Inventory** - List all dependencies
-3. **Verify** - Test each dependency exists
-4. **Fix** - Correct only confirmed issues
-
-**Fix only:**
-- ✅ Confirmed syntax errors
-- ✅ Verified null references
-- ✅ Missing dependencies (after verification)
-- ✅ Real type mismatches
-
-**Never change:**
-- ❌ Unverified resources
-- ❌ Configurations that "seem wrong"
-- ❌ APIs you haven't tested
-- ❌ Working code that could be "better"
-
-## ServiceNow Development Standards
-
-### Table Operations
-- Always verify table existence before operations
-- Use proper field types and references
-- Check for ACLs and permissions
-- Handle large datasets with pagination
-
-### Script Development
-- Use Script Includes for reusable code
-- Implement proper error handling
-- Add meaningful logging with gs.info/warn/error
-- Test in scoped applications when applicable
-
-### Widget Development
-- Ensure HTML/Client/Server coherence
-- Use Angular providers correctly
-- Implement proper data binding
-- Test across different themes and portals
-
-### Flow Development
-- Use proper trigger conditions
-- Implement error handling paths
-- Add appropriate logging actions
-- Test with various data scenarios
-
-## MCP Server Capabilities
-
-Snow-Flow includes 22 specialized MCP servers, each providing comprehensive ServiceNow capabilities:
-
-### 1. ServiceNow Deployment Server
-**Purpose:** Widget and artifact deployment with coherence validation
-
-**Key Tools:**
-- `snow_deploy_widget` - Deploy widgets with HTML/Client/Server validation
-- `snow_deploy_portal_page` - Deploy portal pages
-- `snow_deploy_flow` - Deploy Flow Designer flows
-- `snow_create_update_set` - Create update sets
-- `snow_validate_deployment` - Validate deployed artifacts
-- `snow_rollback_deployment` - Rollback failed deployments
-
-**Special Features:**
-- Automatic widget coherence validation
-- Data flow contract verification
-- Method implementation checking
-- CSS class validation
-
-### 2. ServiceNow Operations Server
-**Purpose:** Core ServiceNow operations and queries
-
-**Key Tools:**
-- `snow_query_table` - Universal table querying with pagination
-- `snow_create_incident` - Create and manage incidents
-- `snow_update_record` - Update any table record
-- `snow_delete_record` - Delete records with validation
-- `snow_discover_table_fields` - Discover table schema
-- `snow_cmdb_search` - Search Configuration Management Database
-
-**Features:**
-- Full CRUD operations on any table
-- Advanced query capabilities
-- Field discovery and validation
-- Relationship navigation
-
-### 3. ServiceNow Automation Server
-**Purpose:** Script execution and automation
-
-**Key Tools:**
-- `snow_execute_script_with_output` - Execute scripts with output capture
-- `snow_get_script_output` - Retrieve script execution history
-- `snow_execute_script_sync` - Synchronous script execution
-- `snow_get_logs` - Access system logs
-- `snow_test_rest_connection` - Test REST integrations
-- `snow_trace_execution` - Trace script execution
-- `snow_schedule_job` - Create scheduled jobs
-- `snow_create_event` - Trigger system events
-
-**Features:**
-- Full output capture (gs.print/info/warn/error)
-- Execution history tracking
-- System log access
-- REST message testing
-- Performance tracing
-
-### 4. ServiceNow Platform Development Server
-**Purpose:** Platform development artifacts
-
-**Key Tools:**
-- `snow_create_script_include` - Create reusable scripts
-- `snow_create_business_rule` - Create business rules
-- `snow_create_client_script` - Create client-side scripts
-- `snow_create_ui_policy` - Create UI policies
-- `snow_create_ui_action` - Create UI actions
-- `snow_create_ui_page` - Create UI pages
-
-**Features:**
-- Full artifact creation
-- Proper scoping support
-- Condition builder integration
-- Script validation
-
-### 5. ServiceNow Integration Server
-**Purpose:** Integration and data management
-
-**Key Tools:**
-- `snow_create_rest_message` - Create REST integrations
-- `snow_create_transform_map` - Create data transformation maps
-- `snow_create_import_set` - Manage import sets
-- `snow_test_web_service` - Test web services
-- `snow_configure_email` - Configure email settings
-
-**Features:**
-- REST/SOAP integration
-- Data transformation
-- Import/Export capabilities
-- Email configuration
-
-### 6. ServiceNow System Properties Server
-**Purpose:** System property management
-
-**Key Tools:**
-- `snow_property_get` - Retrieve property values
-- `snow_property_set` - Set property values
-- `snow_property_list` - List properties by pattern
-- `snow_property_delete` - Remove properties
-- `snow_property_bulk_update` - Bulk operations
-- `snow_property_export` - Export to JSON
-- `snow_property_import` - Import from JSON
-
-**Features:**
-- Full CRUD on sys_properties
-- Bulk operations
-- Import/Export capabilities
-- Property validation
-
-### 7. ServiceNow Update Set Server
-**Purpose:** Change management and deployment with automatic user synchronization
-
-**Key Tools:**
-- `snow_create_update_set` - Create new update sets
-- `snow_ensure_active_update_set` - Ensure active Update Set (auto-syncs current)
-- `snow_sync_current_update_set` - **NEW:** Sync user's current Update Set with Snow-Flow
-- `snow_complete_update_set` - Mark as complete
-- `snow_preview_update_set` - Preview changes
-- `snow_export_update_set` - Export as XML
-
-**🆕 AUTO-SYNC FEATURE:**
-Snow-Flow now automatically sets its Update Set as the user's current Update Set in ServiceNow. This prevents confusion where Snow-Flow works in one Update Set while the user sees a different current Update Set.
-
-**Features:**
-- **Automatic current Update Set synchronization** - user and Snow-Flow always in same Update Set
-- Full update set lifecycle management
-- Change tracking and artifact management
-- XML export/import capabilities
-- Conflict detection and resolution
-
-### 8. ServiceNow Development Assistant Server
-**Purpose:** Code generation and best practices
-
-**Key Tools:**
-- `snow_generate_code` - Generate ServiceNow code
-- `snow_suggest_pattern` - Suggest design patterns
-- `snow_review_code` - Code review and analysis
-- `snow_optimize_performance` - Performance recommendations
-
-**Features:**
-- Pattern-based code generation
-- Best practice enforcement
-- Performance optimization
-- Security review
-
-### 9. ServiceNow Security & Compliance Server
-**Purpose:** Security and compliance management
-
-**Key Tools:**
-- `snow_create_security_policy` - Create security policies
-- `snow_audit_compliance` - Compliance auditing
-- `snow_scan_vulnerabilities` - Vulnerability scanning
-- `snow_assess_risk` - Risk assessment
-- `snow_review_access_control` - ACL review
-
-**Features:**
-- SOX/GDPR/HIPAA compliance
-- Security policy management
-- Vulnerability assessment
-- Access control validation
-
-### 10. ServiceNow Reporting & Analytics Server
-**Purpose:** Reporting and data visualization
-
-**Key Tools:**
-- `snow_create_report` - Create reports
-- `snow_create_dashboard` - Create dashboards
-- `snow_define_kpi` - Define KPIs
-- `snow_schedule_report` - Schedule report delivery
-- `snow_analyze_data_quality` - Data quality analysis
-
-**Features:**
-- Advanced reporting
-- Dashboard creation
-- KPI management
-- Scheduled delivery
-
-### 11. ServiceNow Machine Learning & Predictive Intelligence Server
-**Purpose:** AI/ML capabilities with BOTH native ServiceNow PI and local TensorFlow.js training
-
-**🚨 CRITICAL: Two COMPLETELY Different ML Approaches!**
-
-Snow-Flow provides TWO distinct machine learning approaches. **YOU MUST ASK THE USER which approach they need based on their requirements!**
+### Data Querying & Analysis
 
----
+**Category**: core-operations → query
+**Primary Tools**: `snow_query_table`, `snow_query_incidents`, `snow_cmdb_search`
 
-#### **🏢 Native ServiceNow Predictive Intelligence (NEW! v7.4.0)**
-**Runs:** INSIDE ServiceNow instance (native platform capability)
-**License:** Requires ServiceNow Predictive Intelligence license
-**Use For:** Production ML solutions, enterprise deployments
-**Auto-Retrain:** ✅ Yes (ServiceNow manages lifecycle)
-**Integration:** ✅ Seamless (native ServiceNow tables/records)
-
-**Complete PI Solution Builder (5 Tools):**
-- `snow_create_pi_solution` - Create PI solution definitions (classification, regression, similarity, clustering)
-- `snow_train_pi_solution` - Trigger model training in ServiceNow (10-30 min process)
-- `snow_monitor_pi_training` - Monitor training progress and accuracy metrics
-- `snow_activate_pi_solution` - Activate trained solutions for production use
-- `snow_list_pi_solutions` - List all PI solutions with status and metrics
-
-**Prediction Tools (Use Trained Solutions):**
-- `ml_predictive_intelligence` - Make predictions using activated PI solutions
-- `ml_performance_analytics` - Native Performance Analytics ML integration
-- `ml_hybrid_recommendation` - Hybrid ML recommendations
-
-**When to Recommend Native PI:**
-- ✅ User has Predictive Intelligence license
-- ✅ Production deployment required
-- ✅ Need auto-retrain and lifecycle management
-- ✅ Want native ServiceNow integration
-- ✅ Enterprise scale and support required
-
-**Example Conversation:**
-```
-User: "I need to predict incident categories automatically"
-Agent: "Do you have a ServiceNow Predictive Intelligence license?
-        - If YES: I'll create a native PI solution that trains in ServiceNow
-        - If NO: I can create a local TensorFlow.js model (dev/testing only)"
+```javascript
+// Universal table query:
+await snow_query_table({
+  table: 'incident',
+  query: 'active=true^priority=1',
+  fields: ['number', 'short_description', 'assigned_to'],
+  limit: 100
+});
+
+// Specialized incident query:
+await snow_query_incidents({
+  filters: { active: true, priority: 1 },
+  include_metrics: true
+});
 ```
 
 ---
 
-#### **💻 Local TensorFlow.js ML Training (Experimental)**
-**Runs:** Locally on developer machine (NOT in ServiceNow)
-**License:** Free (no ServiceNow license required)
-**Use For:** Development, testing, experimentation
-**Auto-Retrain:** ❌ No (manual process)
-**Integration:** ⚠️ Limited (requires custom deployment)
-
-**Local ML Tools:**
-- `snow_train_classifier` - Train incident classifier locally with TensorFlow.js
-- `snow_predict_change_risk` - Local change risk prediction
-- `snow_detect_anomalies` - Local anomaly detection
-- `snow_forecast_incidents` - Local incident forecasting with time series
-- `snow_optimize_process` - Local process optimization
-
-**When to Recommend Local TensorFlow.js:**
-- ✅ No Predictive Intelligence license available
-- ✅ Development/testing/proof-of-concept only
-- ✅ Want to experiment with ML before buying license
-- ⚠️ NOT for production use (experimental only)
-
-**Example Conversation:**
-```
-User: "I want to try ML but don't have a PI license yet"
-Agent: "Perfect! I can train a local TensorFlow.js model for testing.
-        Note: This is experimental and not for production.
-        When ready for production, you'll need ServiceNow PI license."
-```
+## 🏆 TOOL SELECTION BEST PRACTICES
+
+### Priority Order:
+
+1. **Specific Tool** > Generic Tool
+   - Use `snow_create_uib_page` instead of `snow_create_record({ table: 'sys_ux_page' })`
+   - Use `snow_query_incidents` instead of `snow_query_table({ table: 'incident' })`
+
+2. **Merged Tool** > Individual Actions (v8.2.0+)
+   - Use `snow_update_set_manage({ action: 'create' })` instead of searching for `snow_update_set_create`
+   - Use `snow_update_set_query({ action: 'current' })` instead of `snow_update_set_current`
+
+3. **High-Level Tool** > Low-Level Script
+   - Use `snow_create_complete_workspace` instead of manual Experience/App Config creation
+   - Use dedicated tools instead of `snow_execute_script_with_output` when possible
+
+4. **Local Sync** > Query for Large Artifacts
+   - Use `snow_pull_artifact` for widget debugging (no token limits!)
+   - Use `snow_query_table` for small metadata lookups
 
 ---
 
-#### **📋 Decision Matrix for AI Agent**
+## 📈 PERFORMANCE OPTIMIZATIONS
 
-**Ask yourself when user requests ML:**
+### Token Efficiency (v8.2.0+)
 
-| User Says | Has PI License? | Recommend |
-|-----------|----------------|-----------|
-| "Create incident predictor" | ✅ Yes | Native PI: `snow_create_pi_solution` → `snow_train_pi_solution` |
-| "Create incident predictor" | ❌ No | Local TensorFlow.js: `snow_train_classifier` + explain limitations |
-| "Production ML solution" | ✅ Yes | Native PI (always) |
-| "Production ML solution" | ❌ No | **STOP:** Explain PI license required for production |
-| "Test/experiment with ML" | Either | Can use local TensorFlow.js, mention PI for production |
-| "Predict on existing solution" | N/A | `ml_predictive_intelligence` (works with trained PI solutions) |
+All tools are now optimized for minimal context usage:
+- **Concise descriptions**: "Create UX workspace" instead of "Create Complete UX Workspace - Executes all 6 steps automatically..."
+- **Compact schemas**: "Table name" instead of "Table name to query (e.g., incident, task, sys_user)"
+- **Metadata-driven discovery**: Use categories to find the right tool faster
 
-**🚨 ALWAYS Ask About License:**
-When user requests ML capabilities, ALWAYS ask:
-1. "Do you have a ServiceNow Predictive Intelligence license?"
-2. "Is this for production use or development/testing?"
+### Context Savings:
 
-**Never assume!** Different licenses = completely different tools!
+| Scenario | Before v8.2.0 | After v8.2.0 | Savings |
+|----------|---------------|--------------|---------|
+| Simple CRUD | ~25,000 tokens | ~11,000 tokens | **56%** |
+| Widget Dev | ~25,000 tokens | ~8,000 tokens | **68%** |
+| UI Builder | ~25,000 tokens | ~10,000 tokens | **60%** |
 
 ---
 
-#### **Complete ML Workflow Examples**
+## 🎓 LEARNING PATH BY COMPLEXITY
 
-**Production Workflow (Native PI):**
-```bash
-# 1. Create solution definition
-snow-flow swarm "create PI solution to predict incident category based on description and caller"
+### Beginner Tools (Start Here!)
 
-# 2. Train in ServiceNow (10-30 min)
-snow-flow swarm "train the incident category predictor"
+**Core Operations:**
+- `snow_query_table` - Query any table
+- `snow_create_record` - Create records
+- `snow_update_record` - Update records
 
-# 3. Monitor training
-snow-flow swarm "check training progress and accuracy"
+**Update Sets:**
+- `snow_update_set_manage` - Manage Update Sets
+- `snow_update_set_query` - Query Update Sets
+- `snow_ensure_active_update_set` - Ensure active Update Set
 
-# 4. Activate for production
-snow-flow swarm "activate incident category predictor with 80% confidence threshold"
+### Intermediate Tools
 
-# 5. Make predictions
-snow-flow swarm "predict category for incident INC0010001"
-```
+**UI Frameworks:**
+- `snow_create_uib_page` - Create UI Builder pages
+- `snow_create_complete_workspace` - Create workspaces
+- `snow_deploy` - Deploy widgets
 
-**Development Workflow (Local TensorFlow.js):**
-```bash
-# Train locally (immediate)
-snow-flow swarm "train local incident classifier for testing"
+**Automation:**
+- `snow_execute_script_with_output` - Execute scripts
+- `snow_execute_flow` - Run flows
 
-# Note: Deployment requires custom integration work
-# Recommend upgrading to PI license for production
-```
+### Advanced Tools
+
+**Integration:**
+- `snow_create_rest_message` - Create REST integrations
+- `snow_create_transform_map` - Transform data
+
+**ML & Analytics:**
+- `snow_create_pi_solution` - Create Predictive Intelligence solutions
+- `snow_train_pi_solution` - Train ML models
 
 ---
 
-**Features:**
-- ✅ **Native ServiceNow PI:** Production-ready, licensed, auto-retrain, full lifecycle
-- ⚠️ **Local TensorFlow.js:** Free, experimental, development only, manual deployment
-
-### 12. ServiceNow Knowledge & Catalog Server
-**Purpose:** Knowledge base and service catalog management
-
-**Key Tools:**
-- `snow_create_knowledge_article` - Create knowledge articles
-- `snow_search_knowledge` - Search knowledge base
-- `snow_create_catalog_item` - Create catalog items
-- `snow_create_catalog_variable` - Create catalog variables
-- `snow_create_catalog_ui_policy` - Create UI policies
-- `snow_order_catalog_item` - Order catalog items
-- `snow_discover_catalogs` - Discover available catalogs
-
-**Features:**
-- Knowledge article management
-- Service catalog configuration
-- Catalog item ordering
-- Variable and policy management
-
-### 13. ServiceNow Change, Virtual Agent & PA Server
-**Purpose:** Change management, Virtual Agent, and Performance Analytics
-
-**Key Tools:**
-- `snow_create_change_request` - Create change requests
-- `snow_schedule_cab_meeting` - Schedule CAB meetings
-- `snow_create_va_topic` - Create Virtual Agent topics
-- `snow_send_va_message` - Send VA messages
-- `snow_create_pa_indicator` - Create PA indicators
-- `snow_create_pa_widget` - Create PA widgets
-- `snow_get_pa_scores` - Get performance scores
-
-**Features:**
-- Change management workflows
-- Virtual Agent configuration
-- Performance Analytics setup
-- CAB meeting management
-
-### 14. ServiceNow Flow, Workspace & Mobile Server + UI Builder
-**Purpose:** Flow Designer, Agent Workspace configuration, Mobile app management, and complete UI Builder integration
-
-**Flow Designer Tools:**
-- `snow_list_flows` - List and discover Flow Designer flows
-- `snow_execute_flow` - Execute existing flows programmatically
-- `snow_get_flow_execution_status` - Monitor flow execution status
-- `snow_get_flow_execution_history` - View flow execution history
-- `snow_get_flow_details` - Get detailed flow configuration
-- `snow_import_flow_from_xml` - Import flows from XML (only programmatic creation method)
-
-**🏗️ COMPLETE UX WORKSPACE CREATION (Official ServiceNow APIs):**
-
-**VERIFIED:** All tools use official ServiceNow Now Experience Framework APIs. Fully tested and production-ready!
-
-**Now Experience Framework Workspace (Recommended):**
-- `snow_create_complete_workspace` - **OFFICIAL:** Complete Now Experience Framework workspace
-- Creates: Experience (sys_ux_experience) → List Menu (sys_ux_list_menu_config) → App Config (sys_ux_app_config) → Page Properties (sys_ux_page_property) → List Configuration (sys_ux_list_category, sys_ux_list) → App Route (sys_ux_app_route)
-- **Fully functional:** Ready for production use with proper ServiceNow architecture
-- Required: `workspace_name`, optional: `tables` for list configuration
-
-**Configurable Agent Workspace (Enterprise):**
-- `snow_create_configurable_agent_workspace` - **OFFICIAL:** Agent Workspace with UX App architecture
-- Creates: App Route (sys_ux_app_route) → Screen Collections (sys_ux_screen_type) for each table
-- **Enterprise features:** Designed for agent productivity and case management
-- Required: `name`, `tables` for screen collections
-
-**Individual Components (for fine control):**
-- `snow_create_ux_experience` - Experience Record (sys_ux_experience)
-- `snow_create_ux_app_config` - App Configuration (sys_ux_app_config)
-- `snow_create_ux_page_macroponent` - Page Macroponent (sys_ux_macroponent)
-- `snow_create_ux_page_registry` - Page Registry (sys_ux_page_registry)
-- `snow_create_ux_app_route` - Route Record (sys_ux_app_route)
-- `snow_update_ux_app_config_landing_page` - Landing Page Configuration
-
-**Workspace Management:**
-- `snow_discover_all_workspaces` - **COMPREHENSIVE:** Discover all workspace types
-- `snow_validate_workspace_configuration` - **BEST PRACTICES:** Validate configuration and performance
-
-
-**Mobile App Tools:**
-- `snow_configure_mobile_app` - Configure mobile applications
-- `snow_send_push_notification` - Send push notifications
-- `snow_configure_offline_sync` - Configure offline sync
-
-**🆕 COMPLETE UI BUILDER + WORKSPACE INTEGRATION (25+ TOOLS!):**
-
-**UI Builder Page Management (sys_ux_page):**
-- `snow_create_uib_page` - Create UI Builder pages with automatic routing
-- `snow_update_uib_page` - Update page configuration and metadata
-- `snow_delete_uib_page` - Delete pages with comprehensive dependency validation
-- `snow_discover_uib_pages` - Find all UI Builder pages with filtering
-
-**UI Builder Component Library (sys_ux_lib_*):**
-- `snow_create_uib_component` - Create custom UI components with source code
-- `snow_update_uib_component` - Update component definitions and source
-- `snow_discover_uib_components` - Browse ServiceNow built-in + custom components
-- `snow_clone_uib_component` - Clone and modify existing components
-
-**UI Builder Data Integration (sys_ux_data_broker):**
-- `snow_create_uib_data_broker` - Connect ServiceNow tables/scripts/REST to pages
-- `snow_configure_uib_data_broker` - Update queries, caching, and refresh settings
-
-**UI Builder Layout Management (sys_ux_page_element):**
-- `snow_add_uib_page_element` - Add components to pages with full configuration
-- `snow_update_uib_page_element` - Update component properties and positioning  
-- `snow_remove_uib_page_element` - Remove elements with dependency checking
-
-**UI Builder Advanced Features:**
-- `snow_create_uib_page_registry` - Configure URL routing and access control
-- `snow_discover_uib_routes` - Find all page routes with security info
-- `snow_create_uib_client_script` - Add client-side JavaScript for pages
-- `snow_create_uib_client_state` - Manage page state and persistence
-- `snow_create_uib_event` - Create custom events for components
-- `snow_analyze_uib_page_performance` - Performance analysis and optimization
-- `snow_validate_uib_page_structure` - Structure validation and best practices
-- `snow_discover_uib_page_usage` - Usage analytics and complexity scoring
-
-**Important:** Flow creation is only supported through Flow Designer UI, not programmatically
-
-**Features:**
-- Flow Designer automation
-- Complete Agent Workspace configuration
-- Mobile app management with push notifications
-- **Complete UI Builder/UXF integration** - Full Now Experience Framework development
-- **Conversational UI development** - Create modern ServiceNow UIs through natural language
-- **Component library management** - Custom component development and reuse
-- **Performance optimization** - Built-in UI Builder performance analysis
-- **Structure validation** - Comprehensive dependency and integrity checking
-
-### 15. ServiceNow CMDB, Event, HR, CSM & DevOps Server
-**Purpose:** CMDB management, Event processing, HR services, Customer Service, and DevOps
-
-**Key Tools:**
-- `snow_create_ci` - Create Configuration Items
-- `snow_create_ci_relationship` - Create CI relationships
-- `snow_run_discovery` - Run discovery
-- `snow_create_event` - Create events
-- `snow_create_hr_case` - Create HR cases
-- `snow_employee_onboarding` - Employee onboarding
-- `snow_create_customer_case` - Create customer cases
-- `snow_create_devops_pipeline` - Create DevOps pipelines
-
-**Features:**
-- CMDB management
-- Event correlation
-- HR case management
-- Customer service management
-- DevOps pipeline integration
-
-### 16. ServiceNow Advanced Features Server
-**Purpose:** Advanced capabilities for optimization and analysis
-
-**Key Tools:**
-- `snow_batch_api` - Batch API operations (80% API reduction)
-- `snow_get_table_relationships` - Analyze table relationships
-- `snow_analyze_query` - Query optimization
-- `snow_detect_code_patterns` - Code pattern detection
-- `snow_discover_process` - Process discovery
-- `snow_analyze_workflow_execution` - Workflow analysis
-- `snow_generate_documentation` - Auto-documentation
-
-**Features:**
-- Batch operations for performance
-- Advanced analytics
-- Process mining
-- Code optimization
-- Automatic documentation
-
-### 17. ServiceNow Local Development Server
-**Purpose:** Bridge between ServiceNow artifacts and Claude Code's native development tools
-
-**Key Tools:**
-- `snow_pull_artifact` - Pull any ServiceNow artifact to local files
-- `snow_push_artifact` - Push local changes back with validation
-- `snow_validate_artifact_coherence` - Validate artifact relationships
-- `snow_list_supported_artifacts` - List all supported artifact types
-- `snow_sync_status` - Check sync status of local artifacts
-- `snow_sync_cleanup` - Clean up local files after sync
-- `snow_convert_to_es5` - Convert modern JavaScript to ES5
-
-**Features:**
-- Supports 12+ artifact types dynamically
-- Smart field chunking for large artifacts
-- ES5 validation for server-side scripts
-- Coherence validation for widgets
-- Full Claude Code native tool integration
-
-**Supported Artifact Types:**
-- Service Portal Widgets (`sp_widget`)
-- Flow Designer Flows (`sys_hub_flow`)
-- Script Includes (`sys_script_include`)
-- Business Rules (`sys_script`)
-- UI Pages (`sys_ui_page`)
-- Client Scripts (`sys_script_client`)
-- UI Policies (`sys_ui_policy`)
-- REST Messages (`sys_rest_message`)
-- Transform Maps (`sys_transform_map`)
-- Scheduled Jobs (`sysauto_script`)
-- Fix Scripts (`sys_script_fix`)
-
-### 18. Snow-Flow Orchestration Server
-**Purpose:** Multi-agent coordination and task management
-
-**Key Tools:**
-- `snow_swarm_init` - Initialize agent swarms
-- `snow_agent_spawn` - Create specialized agents
-- `snow_task_orchestrate` - Orchestrate complex tasks
-- `snow_memory_store` - Persistent memory storage
-- `snow_neural_train` - Train neural networks
-- `snow_performance_analyze` - Performance analysis
-
-**Features:**
-- Multi-agent coordination
-- Task orchestration
-- Neural network training (TensorFlow.js)
-- Memory management
-- Performance monitoring
-
-## Local Development with Artifact Sync
-
-### Dynamic Artifact Synchronization
-
-The Local Development Server enables editing ServiceNow artifacts using Claude Code's native file tools. This creates a powerful development bridge between ServiceNow and local development environments.
-
-**Workflow:**
-
-1. **Pull Artifact to Local Files**
-   ```javascript
-   // Auto-detect artifact type
-   snow_pull_artifact({ sys_id: 'any_sys_id' });
-   
-   // Or specify table for faster pull
-   snow_pull_artifact({ 
-     sys_id: 'widget_sys_id',
-     table: 'sp_widget' 
-   });
-   ```
-
-2. **Edit with Claude Code Native Tools**
-   - Full search capabilities across files
-   - Multi-file editing and refactoring
-   - Syntax highlighting and validation
-   - Git-like diff viewing
-   - Go-to-definition and references
-
-3. **Validate Coherence**
-   ```javascript
-   // Check artifact relationships
-   snow_validate_artifact_coherence({ 
-     sys_id: 'artifact_sys_id' 
-   });
-   ```
-
-4. **Push Changes Back**
-   ```javascript
-   // Push with automatic validation
-   snow_push_artifact({ sys_id: 'artifact_sys_id' });
-   
-   // Force push despite warnings
-   snow_push_artifact({ 
-     sys_id: 'artifact_sys_id',
-     force: true 
-   });
-   ```
-
-5. **Clean Up**
-   ```javascript
-   // Remove local files after sync
-   snow_sync_cleanup({ sys_id: 'artifact_sys_id' });
-   ```
-
-**Artifact Registry:**
-
-Each artifact type is configured with:
-- Field mappings to local files
-- Context-aware wrappers for better editing
-- ES5 validation flags for server scripts
-- Coherence rules for interconnected fields
-- Preprocessors/postprocessors for data transformation
-
-**File Structure Example:**
-```
-/tmp/snow-flow-artifacts/
-├── widgets/
-│   └── my_widget/
-│       ├── my_widget.html          # Template
-│       ├── my_widget.server.js     # Server script (ES5)
-│       ├── my_widget.client.js     # Client script
-│       ├── my_widget.css           # Styles
-│       ├── my_widget.config.json   # Configuration
-│       └── README.md               # Context & instructions
-├── script_includes/
-│   └── MyScriptInclude/
-│       ├── MyScriptInclude.js      # Script
-│       └── MyScriptInclude.docs.md # Documentation
-└── business_rules/
-    └── my_rule/
-        ├── my_rule.js               # Rule script
-        └── my_rule.condition.js     # Condition
-```
+**Last Updated**: v8.2.0 (2025-10-21) - Breaking Changes: Update Set tool merging
 
-**Benefits:**
-- Use your favorite editor features
-- Full search and replace capabilities
-- Version control integration
-- Bulk operations across artifacts
-- Offline development capability
-- Advanced refactoring tools
-
-## Debugging Best Practices
-
-### Systematic Debugging Protocol
-
-1. **Reproduce the Issue**
-   ```javascript
-   // Always use ES5 and test exact code
-   const result = await snow_execute_script_with_output({
-     script: `/* Exact failing code in ES5 */`
-   });
-   ```
-
-2. **Verify Dependencies**
-   - Check all referenced tables exist
-   - Verify all properties are set
-   - Confirm all fields are present
-   - Test all integrations work
-
-3. **Test in Context**
-   - Use same scope and variables
-   - Include same imports
-   - Test with same data
-
-4. **Apply Evidence-Based Fixes**
-   - Fix only confirmed issues
-   - Document why changes were made
-   - Test fixes thoroughly
-
-### Common Verification Patterns
-
-**Table Verification:**
-```javascript
-var table = new GlideRecord('table_name');
-gs.info('Table exists: ' + table.isValid());
-```
 
-**Property Verification:**
+---
+
+## 📊 V8.2.0 FINAL STATISTICS
+
+### Tools Optimized & Merged
+
+**Total Tools:**
+- Before v8.2.0: **411 tools**
+- After v8.2.0: **397 tools**  
+- **Reduction: 14 tools (-3.4%)**
+
+**Merged Categories:**
+
+1. **Update Set Tools: 9 → 3 (6 removed)**
+   - Merged: create, switch, complete, export, preview, add_artifact, current, list
+   - Into: `snow_update_set_manage`, `snow_update_set_query`
+   - Kept: `snow_ensure_active_update_set`
+
+2. **System Properties: 12 → 4 (8 removed)**
+   - Merged: get, set, delete, validate, list, search, categories, bulk_get, bulk_set, import, export, history
+   - Into: `snow_property_manage`, `snow_property_query`, `snow_property_bulk`, `snow_property_io`
+
+### Description Optimization
+
+**All 409 tools** received:
+- ✅ Concise descriptions (verbose → compact)
+- ✅ Metadata (category, subcategory, use_cases, complexity, frequency)
+- ✅ Optimized property descriptions
+
+**Estimated Token Savings:**
+- Description compression: ~300 tokens
+- Full optimization: **~10,000+ tokens** across all tools
+
+### Migration Complexity
+
+**Update Sets Migration:**
 ```javascript
-var prop = gs.getProperty('property.name');
-gs.info('Property value: ' + (prop || 'NOT SET'));
+// OLD: snow_update_set_create({ name, description })
+// NEW: snow_update_set_manage({ action: 'create', name, description })
 ```
+**Effort:** Very Low (add action parameter)
 
-**Field Verification:**
+**System Properties Migration:**
 ```javascript
-var gr = new GlideRecord('table');
-var element = gr.getElement('field_name');
-gs.info('Field exists: ' + (element ? 'Yes' : 'No'));
+// OLD: snow_property_get({ name })
+// NEW: snow_property_manage({ action: 'get', name })
 ```
+**Effort:** Very Low (add action parameter)
+
+---
 
-## Command Reference
-
-### Core Commands
-- `./snow-flow start` - Start orchestration system
-- `./snow-flow status` - System status
-- `./snow-flow monitor` - Real-time monitoring
-
-### Agent Management
-- `./snow-flow agent spawn <type>` - Create agents
-- `./snow-flow agent list` - List active agents
-
-### Task Management
-- `./snow-flow task create` - Create tasks
-- `./snow-flow task list` - View task queue
-
-### Memory Operations
-- `./snow-flow memory store <key> <data>` - Store data
-- `./snow-flow memory get <key>` - Retrieve data
-- `./snow-flow memory list` - List all keys
-
-### SPARC Modes
-- `./snow-flow sparc "<task>"` - Orchestrator mode
-- `./snow-flow sparc run <mode> "<task>"` - Specific mode
-- `./snow-flow sparc tdd "<feature>"` - Test-driven development
-
-### Swarm Coordination
-- `./snow-flow swarm "<objective>"` - Multi-agent coordination
-- Options: `--strategy`, `--mode`, `--parallel`, `--monitor`
-
-## Workflow Guidelines
-
-### Development Workflow
-1. **Plan** - Use TodoWrite for task management
-2. **Verify** - Check existing resources
-3. **Develop** - Follow ES5 standards
-4. **Test** - Use background scripts
-5. **Deploy** - Use update sets
-6. **Validate** - Verify deployment
-
-### Testing Workflow
-1. Run unit tests with background scripts
-2. Test integrations with REST tools
-3. Validate UI with widget coherence
-4. Check performance with tracing
-5. Review logs for errors
-
-### Debugging Workflow
-1. Reproduce issue exactly
-2. Gather evidence with scripts
-3. Verify all assumptions
-4. Apply minimal fixes
-5. Test thoroughly
-6. Document changes
-
-## Important Reminders
-
-### Always Remember
-- Every ServiceNow instance is unique
-- Custom implementations exist that you don't know about
-- Preview/beta features may be available
-- Organization-specific configurations are common
-- Test everything before making assumptions
-
-### Never Assume
-- That something doesn't exist without verification
-- That configurations are wrong without testing
-- That APIs aren't available without checking
-- That code won't work without running it
-- That you know better than existing implementations
-
-### Golden Rules
-1. **Verify First** - Test before declaring broken
-2. **ES5 Only** - No modern JavaScript in ServiceNow
-3. **Evidence-Based** - Make decisions on facts, not assumptions
-4. **Minimal Changes** - Fix only what's broken
-5. **Respect Context** - Understand why things exist as they do
-
-## Conclusion
-
-Snow-Flow is a powerful framework for ServiceNow development that emphasizes verification, testing, and evidence-based decision making. By following these guidelines and best practices, you ensure reliable, maintainable, and effective ServiceNow solutions.
-
-Remember: Your job is to solve problems, not to judge implementations. Every environment has its reasons for existing configurations. Verify, test, and respect what you find.