intune-api.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "Intune AI Scout API",
    "version": "3.0",
    "description": "Azure Functions API for Microsoft Intune device management and Microsoft Defender for Endpoint security operations. Direct Azure Functions endpoints with function key authentication. Provides comprehensive device inventory, compliance monitoring, security assessments, threat management, PowerShell and shell script management, and advanced application filtering capabilities with hybrid server/client-side filtering for enterprise IT and security teams."
  },
  "host": "your-function-app.azurewebsites.net",
  "basePath": "/api",
  "schemes": [
    "https"
  ],
  "consumes": [],
  "produces": [],
  "paths": {
    "/intune/devices": {
      "get": {
        "operationId": "GetIntuneDevices",
        "summary": "Get Intune Devices",
        "description": "Retrieves Intune device inventory with extended properties (uses BETA API). Returns 85+ properties including autopilotEnrolled, malwareCounts, hardwareInformation, processorArchitecture. Use when user asks to list, show, find, or query devices. CRITICAL: Execute immediately without prompting for optional parameters. When user says 'show devices' or 'list devices' with NO criteria, call with filter=null and top=25. Only construct filter when user explicitly mentions OS, compliance, ownership, user, or date criteria. Examples: 'show devices'->filter=null,top=25; '5 Windows devices'->filter=operatingSystem eq 'Windows',top=5; 'compliant devices'->filter=complianceState eq 'compliant',top=25. Do NOT use for single device by ID (use GetIntuneDeviceById instead).",
        "tags": [
          "Intune Device Management"
        ],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Use null/empty when user says 'show devices' or 'list devices'. Only construct filter when user explicitly mentions criteria: OS ('Windows'->operatingSystem eq 'Windows'; 'iOS'->operatingSystem eq 'iOS'; 'Android'->operatingSystem eq 'Android'), Compliance ('compliant'->complianceState eq 'compliant'; 'non-compliant'->complianceState eq 'noncompliant'), Ownership ('corporate'->managedDeviceOwnerType eq 'company'; 'personal'->managedDeviceOwnerType eq 'personal'), User ('owned by name'->userPrincipalName eq 'user@domain.com'), Date ('last 2 days'->lastSyncDateTime ge [ISO8601 date, calculate current date minus 2 days in format 2025-10-19T00:00:00Z]). For dates, calculate ISO 8601 datetime - never use now() function. Combine with 'and' operator.",
            "x-example": "operatingSystem eq 'Android' and userPrincipalName eq 'user@domain.com' and lastSyncDateTime ge 2025-10-19T00:00:00Z"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Always provide a value automatically. Extraction rules: '5 devices'/'show 5'->5, '10 devices'/'top 10'->10, '50 devices'->50, '100 devices'->100, NO number specified->25 (default for chat). Maximum: 200. Backend default: 100.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved device list",
            "schema": {
              "type": "object",
              "properties": {
                "devices": {
                  "type": "array",
                  "description": "Array of managed device objects with extended BETA properties including: id, deviceName, operatingSystem, osVersion, complianceState, lastSyncDateTime, enrolledDateTime, userPrincipalName, model, manufacturer, serialNumber, autopilotEnrolled, deviceFirmwareConfigurationInterfaceManaged, windowsActiveMalwareCount, windowsRemediatedMalwareCount, hardwareInformation, processorArchitecture, physicalMemoryInBytes, ethernetMacAddress, specificationVersion, bootstrapTokenEscrowed",
                  "items": {
                    "type": "object"
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of devices returned in this response"
                },
                "nextLink": {
                  "type": "string",
                  "description": "OData nextLink for pagination if more results are available"
                },
                "timestamp": {
                  "type": "string",
                  
                  "description": "ISO 8601 timestamp when the request was processed"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid filter expression or parameters"
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key"
          },
          "500": {
            "description": "Internal server error - check logs for details",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          }
        },
        "x-code-samples": [
          {
            "lang": "PowerShell",
            "source": "# Get all devices (default 100)\nInvoke-RestMethod -Uri 'https://your-function-app.azurewebsites.net/api/intune/devices?code=<function-key>' -Method GET\n\n# Filter by Windows devices\nInvoke-RestMethod -Uri 'https://your-function-app.azurewebsites.net/api/intune/devices?filter=operatingSystem%20eq%20%27Windows%27&code=<function-key>' -Method GET\n\n# Get top 25 non-compliant devices\nInvoke-RestMethod -Uri 'https://your-function-app.azurewebsites.net/api/intune/devices?filter=complianceState%20eq%20%27noncompliant%27&top=25&code=<function-key>' -Method GET\n\n# Complex filter: Corporate Windows devices that are compliant\nInvoke-RestMethod -Uri 'https://your-function-app.azurewebsites.net/api/intune/devices?filter=operatingSystem%20eq%20%27Windows%27%20and%20complianceState%20eq%20%27compliant%27%20and%20managedDeviceOwnerType%20eq%20%27company%27&code=<function-key>' -Method GET"
          }
        ]
      }
    },
    "/intune/device": {
      "get": {
        "operationId": "GetIntuneDeviceById",
        "summary": "Get Intune Device by ID",
        "description": "Retrieves detailed device information using unique Intune device identifier. Returns comprehensive profile: hardware specs, software config, compliance policies, security settings. Wraps Microsoft Graph API deviceManagement/managedDevices/{id} with simplified auth via Azure Function keys and managed identity. Use when user asks to get/retrieve/show specific device by ID. Do NOT use for listing multiple devices or filtering (use GetIntuneDevices).\n\nFor AI/Chat: Only call with real, valid Intune device GUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with hex values). If user provides device name, example ID, or uncertain if ID is real, use GetIntuneDevices first to search and extract real device ID. If returns 404, inform user device ID doesn't exist and suggest searching by name via GetIntuneDevices.",
        "tags": [
          "Intune Device Management"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune device identifier (GUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Must be a real device GUID from Intune, not device name, serial number, or Azure AD device ID. If user provides device name or you don't have a confirmed valid device GUID, call GetIntuneDevices first to search and extract the real device ID.",
            "x-example": "f020be15-349e-4560-b2a7-3bd2dde3cb18"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved device details"
          },
          "400": {
            "description": "Bad request - missing or invalid device ID parameter"
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key"
          },
          "404": {
            "description": "Device not found - no device exists with the provided ID"
          },
          "500": {
            "description": "Internal server error - check logs for details"
          }
        }
      }
    },
    "/intune/device/{deviceId}/action": {
      "post": {
        "operationId": "IntuneRemoteAction",
        "summary": "Intune Remote Action",
        "description": "Execute management action on Intune device. Supports: sync (force check-in), reboot, remoteLock, windowsDefenderScan, windowsDefenderFullScan, collectDiagnostics, rename. Use when user says 'sync device', 'reboot device', 'lock device', 'scan device for malware'. WORKFLOW: If user provides device name, first call GetIntuneDevices to get deviceId, then call this. Examples: 'sync my laptop'->GetIntuneDevices(laptop)->IntuneRemoteAction(id, sync); 'reboot DESKTOP-ABC'->action:reboot; 'run defender scan on device X'->action:windowsDefenderScan.",
        "tags": [
          "Intune Device Management"
        ],
        "consumes": ["application/json"],
        "parameters": [
          {
            "name": "deviceId",
            "in": "path",
            "type": "string",
            "required": true,
            "description": "REQUIRED: Intune device ID (GUID). If user provides device name, first call GetIntuneDevices to find ID.",
            "x-example": "f020be15-349e-4560-b2a7-3bd2dde3cb18"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["action"],
              "properties": {
                "action": {
                  "type": "string",
                  "enum": ["sync", "reboot", "remoteLock", "windowsDefenderScan", "windowsDefenderFullScan", "collectDiagnostics", "rename"],
                  "description": "REQUIRED: Action to execute. 'sync'->force device check-in, 'reboot'->restart device, 'remoteLock'->lock device, 'windowsDefenderScan'->run quick AV scan, 'windowsDefenderFullScan'->run full AV scan, 'collectDiagnostics'->collect logs, 'rename'->rename device (requires newName)."
                },
                "newName": {
                  "type": "string",
                  "description": "REQUIRED for rename action. New device name."
                },
                "scanType": {
                  "type": "string",
                  "enum": ["quick", "full"],
                  "description": "OPTIONAL for windowsDefenderScan. 'quick' (default) or 'full' scan."
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Action executed successfully",
            "schema": {
              "type": "object",
              "properties": {
                "success": { "type": "boolean" },
                "message": { "type": "string" },
                "action": { "type": "string" },
                "actionDescription": { "type": "string" },
                "device": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "deviceName": { "type": "string" },
                    "operatingSystem": { "type": "string" },
                    "userPrincipalName": { "type": "string" }
                  }
                },
                "note": { "type": "string" }
              }
            }
          },
          "400": { "description": "Bad request - invalid action, missing confirmation for destructive action, or missing required parameters" },
          "401": { "description": "Unauthorized - invalid API key" },
          "403": { "description": "Forbidden - requires DeviceManagementManagedDevices.ReadWrite.All permission" },
          "404": { "description": "Device not found" }
        }
      }
    },
    "/intune/compliance": {
      "get": {
        "operationId": "GetIntuneCompliance",
        "summary": "Get Intune Compliance",
        "description": "Returns organizational compliance summary and policy list with extended properties (uses BETA API). Returns 45+ properties per policy including roleScopeTagIds, version, validOperatingSystemBuildRanges. Use for org-wide statistics. Do NOT use for device lists (use GetIntuneDevices). CRITICAL: Execute immediately without prompting for optional parameters. When user says 'show compliance' or 'compliance status' with NO criteria, call with filter=null and top=25. Only construct filter when user explicitly mentions platform or policy name. Examples: 'show compliance'->filter=null,top=25; '5 Windows policies'->filter=platformType eq 'windows10',top=5; 'iOS policies'->filter=platformType eq 'iOS',top=25.",
        "tags": [
          "Intune Compliance"
        ],
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Always provide a value automatically. Extraction rules: '5 policies'/'show 5'->5, '10 policies'->10, NO number specified->25 (default for chat). Maximum: 200. Backend default: 100.",
            "x-example": 25
          },
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Use null/empty when user says 'show compliance' or 'compliance status'. Only construct filter when user explicitly mentions: Platform ('Windows'->platformType eq 'windows10'; 'iOS'->platformType eq 'iOS'; 'Android'->platformType eq 'android'), Policy name (displayName eq 'PolicyName'). Combine with 'and' operator.",
            "x-example": "platformType eq 'windows10'"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved compliance data",
            "schema": {
              "type": "object",
              "properties": {
                "summary": {
                  "type": "object",
                  "description": "Organization-wide compliance summary with device counts by state"
                },
                "policies": {
                  "type": "array",
                  "description": "Array of compliance policy objects with extended BETA properties including: id, displayName, description, version, createdDateTime, lastModifiedDateTime, roleScopeTagIds, platformType, validOperatingSystemBuildRanges",
                  "items": {
                    "type": "object"
                  }
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp when the request was processed"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid filter expression or parameters"
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key"
          },
          "500": {
            "description": "Internal server error - check logs for details"
          }
        }
      }
    },
    "/intune/device-apps": {
      "get": {
        "operationId": "GetIntuneDeviceApps",
        "summary": "Get Intune Device Applications",
        "description": "Returns applications INSTALLED on a SPECIFIC device. ONLY use when user explicitly mentions a device name or device ID with phrases like 'apps on device X', 'installed on X', 'software on X'. Requires deviceId parameter. Do NOT use for 'show apps', 'list apps', 'managed apps', 'app catalog' - use GetIntuneManagedApps for those. CRITICAL: If no device is mentioned in the query, DO NOT use this tool. If user provides device name instead of ID, first call GetIntuneDevices to get ID. Examples: 'apps on device COPILOT-YES'->THIS TOOL; 'what's installed on 2959a5a5-...'->THIS TOOL; 'show apps'->WRONG use GetIntuneManagedApps; 'list applications'->WRONG use GetIntuneManagedApps.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "deviceId",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune device identifier (GUID format). If user provides device name instead of ID, first call GetIntuneDevices to find the device and extract its ID. Extract from user message or previous GetIntuneDevices response.",
            "x-example": "2959a5a5-6c36-4bf7-bc4d-4e3e07e55388"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Always provide a value automatically. Extraction rules: '5 apps'/'show 5'->5, '10 applications'/'top 10'->10, NO number specified->25 (default for chat). Backend default: 100. Maximum: 200.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved device applications",
            "schema": {
              "type": "object",
              "properties": {
                "applications": {
                  "type": "array",
                  "description": "Array of detected application objects installed on the device",
                  "items": {
                    "type": "object"
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of applications returned in this response (respects top parameter)"
                },
                "deviceId": {
                  "type": "string",
                  "description": "The device identifier that was queried"
                },
                "nextLink": {
                  "type": "string",
                  "description": "OData nextLink for pagination if more results are available"
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp when the request was processed"
                },
                "note": {
                  "type": "string",
                  "description": "API usage note"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Device not found"
          }
        }
      }
    },
    "/intune/apps": {
      "get": {
        "operationId": "GetIntuneManagedApps",
        "summary": "Get Intune Managed Applications",
        "description": "Returns Intune app catalog - ALL managed apps in the tenant. CRITICAL: Use THIS tool FIRST to check if an app exists before any assignment operation. When user says 'assign X to Y', call this with filter=contains(displayName,'X') to get the appId. Also use for: 'show apps', 'list apps', 'find app'. Do NOT use AddWingetAppToIntune for assignment - that creates NEW apps. Workflow for 'assign app to group': 1) GetIntuneManagedApps(filter) to get appId, 2) GetAzureADGroups to get groupId, 3) AssignIntuneApp with both IDs. Examples: 'assign Speedtest to IT'->filter=contains(displayName,'Speedtest'); 'show apps'->filter=null,top=25.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum applications to return. Use top=25 by default. Backend default: 100. Maximum: 200. Only modify if user explicitly says 'show X apps'. Handles Graph API pagination automatically to ensure exact count is returned. When client-side filtering is used (osType, appType, version), fetches larger batch then applies filter and returns exactly top items."
          },
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Leave to null if no filter criteria specified. OData filter for server-side filtering. Set only when user mentions specific criteria. Default: 'show apps'/'list applications'/'managed apps'->filter=null."
          },
          {
            "name": "select",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Comma-separated list of fields to include in response. Leave to null for all fields."
          },
          {
            "name": "osType",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Leave null if no OS specified. Set only when user mentions OS: 'Windows'->windows, 'Android'->android, 'iOS'->ios, 'macOS'->macos. Default: null."
          },
          {
            "name": "appType",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Leave null if no app type specified. Set only when user mentions type: 'store apps'->store, 'LOB apps'->lob, 'web apps'->web, 'winget apps'->winget. Default: null."
          },
          {
            "name": "publisher",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Leave null if no publisher specified. Set only when user mentions specific publisher name. Example: 'Microsoft apps'->Microsoft. Default: null."
          },
          {
            "name": "version",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Leave null if no version specified. Filter by application version - uses client-side filtering. Default: null."
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved managed applications with filtering metadata",
            "schema": {
              "type": "object",
              "properties": {
                "apps": {
                  "type": "array",
                  "description": "Array of managed application objects from Intune",
                  "items": {
                    "type": "object"
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of applications returned"
                },
                "filterApplied": {
                  "type": "object",
                  "description": "Details of applied filters (server-side and client-side)"
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          }
        }
      }
    },
    "/intune/windows-apps": {
      "post": {
        "operationId": "DeployWindowsApp",
        "summary": "Deploy Windows App (Unified)",
        "description": "UNIFIED Windows app deployment - auto-detects installer type and routes to appropriate method. USE THIS for ALL Windows app deployments. Just provide packageId and it handles everything: fetches from WinGet, detects installer type, auto-generates installCommand, deploys correctly. Routing: EXE->Win32, MSI->LOB (windowsMobileMSI), MSIX->WinGet (winGetApp with auto-updates). Execute immediately with just packageId. Examples: 'deploy Git'->packageId:Git.Git; 'deploy 7-Zip'->packageId:7zip.7zip; 'deploy Windows Terminal'->packageId:Microsoft.WindowsTerminal.",
        "tags": [
          "Intune Application Management"
        ],
        "consumes": ["application/json"],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["packageId"],
              "properties": {
                "packageId": {
                  "type": "string",
                  "description": "REQUIRED: WinGet package ID in Publisher.AppName format. Auto-detects installer type: EXE->Win32, MSI->LOB, MSIX->WinGet."
                },
                "architecture": {
                  "type": "string",
                  "enum": ["x64", "x86", "arm64"],
                  "description": "OPTIONAL: DO NOT ask user. Preferred architecture. Default: x64."
                },
                "displayName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Auto-generated from WinGet metadata."
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Auto-generated from WinGet metadata."
                },
                "publisher": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Auto-fetched from WinGet."
                },
                "version": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Specific version to deploy. If not provided, uses latest version from WinGet. Set when user mentions specific version. Leave empty for latest."
                },
                "installCommand": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Auto-generated from WinGet silent switches. Only needed for custom install args."
                },
                "updateExisting": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT ask user. Set true when user says 'update', 'redeploy', 'upgrade', 'refresh', 'new version', or 'reinstall'. If 409 Conflict received, suggest user retry with update option."
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "App deployed successfully to Intune",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "unifiedDeployment": { "type": "boolean", "description": "Always true - indicates unified endpoint was used" },
                "packageId": { "type": "string" },
                "deploymentMethod": { "type": "string", "enum": ["win32", "lob", "winget"], "description": "Deployment method used: win32 for EXE, lob for MSI, winget for MSIX" },
                "installerType": { "type": "string", "description": "Detected installer type: exe, msi, msix, inno, nullsoft, wix, etc." },
                "detectedMetadata": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "version": { "type": "string" },
                    "publisher": { "type": "string" },
                    "architecture": { "type": "string" }
                  }
                },
                "app": {
                  "type": "object",
                  "description": "The created/updated Intune app details",
                  "properties": {
                    "id": { "type": "string" },
                    "displayName": { "type": "string" },
                    "displayVersion": { "type": "string" }
                  }
                },
                "operation": { "type": "string", "enum": ["create", "update", "existing"] },
                "nextSteps": { "type": "array", "items": { "type": "string" } },
                "correlationId": { "type": "string" }
              }
            }
          },
          "400": { "description": "Bad request - invalid packageId or no installers found" },
          "401": { "description": "Unauthorized - invalid API key" }
        }
      }
    },
    "/intune/winget-apps": {
      "post": {
        "operationId": "AddWingetAppToIntune",
        "summary": "Add Microsoft Store App to Intune",
        "description": "Adds Microsoft Store app to Intune with auto-fetched metadata. ONLY for apps available in Microsoft Store. For desktop apps not in MS Store, use CreateIntuneLOBApp or DeployWindowsApp. AUTO-METADATA: When displayName/publisher not provided, automatically fetches from Microsoft Store using Product ID. WORKFLOW: SearchWindowsApps(source=msstore)->AddWingetAppToIntune. RESPONSE HANDLING: If alreadyExists=true, inform user '[displayName] is already in Intune' and STOP. If app created successfully, inform user '[displayName] has been added to Intune' and STOP. CRITICAL: NEVER ask about assignment or call AssignIntuneApp UNLESS the user's original request explicitly mentioned 'assign', 'deploy to', or a group name.",
        "tags": [
          "Intune Application Management"
        ],
        "consumes": ["application/json"],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["packageIdentifier"],
              "properties": {
                "packageIdentifier": {
                  "type": "string",
                  "description": "REQUIRED: Microsoft Store Product ID from SearchWindowsApps msstore results. Must be alphanumeric 9-14 chars (e.g., XPDM1ZW6815MQM for VLC, 9NBLGGH4Z1JC). DO NOT use WinGet community IDs (Publisher.Package format) - they will NOT work."
                },
                "displayName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user. Auto-fetched from Microsoft Store if not provided. Only set if user explicitly specifies a custom name."
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user. Auto-fetched from Microsoft Store if not provided."
                },
                "publisher": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user. Auto-fetched from Microsoft Store if not provided (e.g., 'VideoLAN' for VLC)."
                },
                "installExperience": {
                  "type": "string",
                  "enum": ["system", "user"],
                  "description": "OPTIONAL: DO NOT prompt user. Installation context. 'system' (default) installs for all users, 'user' installs for current user only."
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "App already exists in Intune (alreadyExists=true) OR app created successfully. If alreadyExists=true, just inform user: '[displayName] is already in Intune.' Do NOT offer assignment unless user requested it.",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "alreadyExists": { "type": "boolean", "description": "If true, app already exists in Intune" },
                "existingApp": {
                  "type": "object",
                  "description": "Present when alreadyExists=true",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID" },
                    "displayName": { "type": "string" },
                    "packageIdentifier": { "type": "string" }
                  }
                },
                "app": {
                  "type": "object",
                  "description": "Present when new app created",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID" },
                    "displayName": { "type": "string" },
                    "packageIdentifier": { "type": "string" },
                    "publisher": { "type": "string" },
                    "installExperience": { "type": "object" }
                  }
                },
                "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }
              }
            }
          },
          "201": {
            "description": "WinGet app created successfully. Inform user: '[displayName] has been added to Intune.' Do NOT offer assignment unless user requested it.",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "app": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID" },
                    "displayName": { "type": "string" },
                    "packageIdentifier": { "type": "string" },
                    "publisher": { "type": "string" },
                    "installExperience": { "type": "object" }
                  }
                },
                "timestamp": { "type": "string" }
              }
            }
          },
          "400": { "description": "Bad request - invalid packageIdentifier or missing required fields" },
          "401": { "description": "Unauthorized - invalid API key" }
        }
      }
    },
    "/intune/android/lob-apps": {
      "post": {
        "operationId": "CreateAndroidLOBApp",
        "summary": "Deploy Android LOB App (APK Upload)",
        "description": "Uploads Android APK file to Intune as a Line-of-Business app. Use for internal/enterprise Android apps not on Play Store. Requires APK download URL and package ID. The file is encrypted and uploaded to Azure Blob Storage. Use updateExisting:true to update existing app with new APK version. For Play Store apps, use AddAndroidStoreApp instead. Max size: 100MB. Examples: 'deploy company app.apk to Android'->installerUrl:https://..., packageId:com.company.app; 'update Android LOB app'->updateExisting:true.",
        "tags": [
          "Intune Application Management"
        ],
        "consumes": ["application/json"],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["installerUrl", "packageId"],
              "properties": {
                "installerUrl": {
                  "type": "string",
                  "description": "REQUIRED: Direct download URL for the APK file."
                },
                "packageId": {
                  "type": "string",
                  "description": "REQUIRED: Android package identifier (e.g., 'com.company.myapp'). Used for app detection."
                },
                "displayName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Display name in Intune. Auto-generated from filename if not provided."
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. App description for Intune portal."
                },
                "publisher": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Publisher name. Defaults to 'Unknown'."
                },
                "versionName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Version display name (e.g., '1.2.3'). Defaults to '1.0.0'."
                },
                "versionCode": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Version code integer as string (e.g., '123'). Defaults to '1'."
                },
                "minimumAndroidVersion": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Minimum Android version (e.g., '9.0', '11.0'). Defaults to '9.0'.",
                  "enum": ["4.0", "4.1", "4.2", "4.3", "4.4", "5.0", "5.1", "6.0", "7.0", "7.1", "8.0", "8.1", "9.0", "10.0", "11.0", "12.0", "13.0", "14.0", "15.0"]
                },
                "updateExisting": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT ask user. Set true to update existing app with same displayName. Default: false."
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Android LOB app updated with new version successfully",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "operation": { "type": "string", "enum": ["update"] },
                "app": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID" },
                    "displayName": { "type": "string" },
                    "packageId": { "type": "string" },
                    "versionName": { "type": "string" },
                    "versionCode": { "type": "string" },
                    "@odata.type": { "type": "string" }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Android LOB app created and uploaded successfully",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "operation": { "type": "string", "enum": ["create"] },
                "app": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID - use for AssignIntuneApp" },
                    "displayName": { "type": "string" },
                    "packageId": { "type": "string" },
                    "versionName": { "type": "string" },
                    "versionCode": { "type": "string" },
                    "@odata.type": { "type": "string", "description": "androidLobApp" },
                    "fileName": { "type": "string" },
                    "fileSize": { "type": "integer" },
                    "fileSizeFormatted": { "type": "string" }
                  }
                },
                "processingTime": { "type": "object" },
                "nextSteps": { "type": "object" }
              }
            }
          },
          "400": { "description": "Bad request - invalid URL, missing packageId, or file too large" },
          "401": { "description": "Unauthorized - invalid API key" },
          "403": { "description": "Forbidden - requires DeviceManagementApps.ReadWrite.All permission" },
          "409": { "description": "Conflict - Android LOB app with same name exists. Use updateExisting:true to update." }
        }
      }
    },
    "/intune/android/store-apps": {
      "post": {
        "operationId": "AddAndroidStoreApp",
        "summary": "Add Android Play Store App",
        "description": "Adds a public Google Play Store app to Intune. Provide the Play Store URL and display name. No file upload needed. For internal/enterprise APK files, use CreateAndroidLOBApp instead.",
        "tags": [
          "Intune Application Management"
        ],
        "consumes": ["application/json"],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["appStoreUrl", "displayName"],
              "properties": {
                "appStoreUrl": {
                  "type": "string",
                  "description": "REQUIRED: Google Play Store URL. Format: https://play.google.com/store/apps/details?id=<package_id>"
                },
                "displayName": {
                  "type": "string",
                  "description": "REQUIRED: Display name for the app in Intune."
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. App description for Intune portal."
                },
                "publisher": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Publisher name. Defaults to 'Unknown'."
                },
                "minimumAndroidVersion": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT ask user. Minimum Android version. Defaults to '9.0'.",
                  "enum": ["4.0", "4.1", "4.2", "4.3", "4.4", "5.0", "5.1", "6.0", "7.0", "7.1", "8.0", "8.1", "9.0", "10.0", "11.0", "12.0", "13.0", "14.0", "15.0"]
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Android Store app added successfully",
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" },
                "app": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "description": "Intune app ID - use for AssignIntuneApp" },
                    "displayName": { "type": "string" },
                    "appStoreUrl": { "type": "string" },
                    "packageId": { "type": "string", "description": "Extracted from Play Store URL" },
                    "@odata.type": { "type": "string", "description": "androidStoreApp" },
                    "publishingState": { "type": "string" }
                  }
                },
                "nextSteps": { "type": "object" }
              }
            }
          },
          "400": { "description": "Bad request - invalid Play Store URL or missing required fields" },
          "401": { "description": "Unauthorized - invalid API key" },
          "403": { "description": "Forbidden - requires DeviceManagementApps.ReadWrite.All permission" },
          "409": { "description": "Conflict - Android Store app with same name already exists" }
        }
      }
    },
    "/intune/app/{appId}": {
      "get": {
        "operationId": "GetIntuneAppById",
        "summary": "Get Intune Application by ID",
        "description": "Returns detailed information for specific Intune managed application including metadata, deployment settings, publisher, version. Use ONLY when user provides app ID directly OR you already have app ID from another tool. Do NOT use when user provides app name (use GetIntuneManagedApps which returns same details). Do NOT use for listing apps or apps on device. Execute immediately when appId available.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "appId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune application identifier (GUID format). If user provides app name instead of ID, first call GetIntuneManagedApps to find the app and extract its ID.",
            "x-example": "189e98a2-5568-437e-94ec-c723b4526794"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved application details"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Application not found"
          }
        }
      },
      "delete": {
        "operationId": "DeleteIntuneApp",
        "summary": "Delete Intune Application",
        "description": "Permanently deletes Intune managed application from tenant. CRITICAL: Destructive operation - confirm with user before executing. Use when user asks to delete, remove, or uninstall app from Intune (not from devices). Do NOT use for removing assignments (use different tool). Best practice: Remove all assignments before deletion to avoid conflicts. Execute only after explicit user confirmation.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "appId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune application identifier (GUID format) to delete. If user provides app name, first call GetIntuneManagedApps to find ID. ALWAYS confirm deletion intent with user before executing.",
            "x-example": "189e98a2-5568-437e-94ec-c723b4526794"
          }
        ],
        "responses": {
          "200": {
            "description": "Application deleted successfully",
            "schema": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean",
                  "description": "Deletion operation success status"
                },
                "appId": {
                  "type": "string",
                  "description": "ID of the deleted application"
                },
                "message": {
                  "type": "string",
                  "description": "Confirmation message"
                },
                "timestamp": {
                  "type": "string",
                  
                  "description": "ISO 8601 timestamp of deletion"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid application ID"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "403": {
            "description": "Forbidden - insufficient permissions. Requires DeviceManagementApps.ReadWrite.All"
          },
          "404": {
            "description": "Application not found - verify appId exists"
          },
          "409": {
            "description": "Conflict - application has active assignments or dependencies. Remove assignments first"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/intune/app/{appId}/assignments": {
      "post": {
        "operationId": "AssignIntuneApp",
        "summary": "Assign Intune Application to Group",
        "description": "Assigns EXISTING Intune app to Azure AD group. CRITICAL WORKFLOW: When user says 'assign X to group Y': 1) GetIntuneManagedApps to find app ID, 2) GetAzureADGroups(search='Y') to find group ID. GROUP NOT FOUND HANDLING: If GetAzureADGroups returns empty results, ASK user: 'Group [Y] was not found. Would you like me to: a) Create a new group called [Y], or b) Search for a similar group name?' If user confirms create->CreateAzureADGroup(displayName='Y', mailNickname=derived)->then AssignIntuneApp with new groupId. Do NOT use AddWingetAppToIntune - that's only for importing NEW apps. Valid @odata.type: groupAssignmentTarget (requires groupId), allLicensedUsersAssignmentTarget, allDevicesAssignmentTarget. Valid intent: required (auto-install), available (optional), uninstall. Default intent: required.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "appId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune application identifier (GUID format).",
            "x-example": "189e98a2-5568-437e-94ec-c723b4526794"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["target", "intent"],
              "properties": {
                "target": {
                  "type": "object",
                  "description": "REQUIRED: Assignment target object. Extract from context: 'to group X'->groupAssignmentTarget with groupId, 'all users'->allLicensedUsersAssignmentTarget, 'all devices'->allDevicesAssignmentTarget. IMPORTANT: allUsersAssignmentTarget does NOT exist - use allLicensedUsersAssignmentTarget.",
                  "required": ["@odata.type"],
                  "properties": {
                    "@odata.type": {
                      "type": "string",
                      "description": "REQUIRED: Target type with # prefix. Extract from context: 'to group'/'group id'->#microsoft.graph.groupAssignmentTarget, 'all users'->#microsoft.graph.allLicensedUsersAssignmentTarget, 'all devices'->#microsoft.graph.allDevicesAssignmentTarget. Default: #microsoft.graph.groupAssignmentTarget if groupId provided.",
                      "enum": ["#microsoft.graph.groupAssignmentTarget", "#microsoft.graph.allLicensedUsersAssignmentTarget", "#microsoft.graph.allDevicesAssignmentTarget", "#microsoft.graph.exclusionGroupAssignmentTarget"],
                      "x-example": "#microsoft.graph.allLicensedUsersAssignmentTarget"
                    },
                    "groupId": {
                      "type": "string",
                      "description": "OPTIONAL: DO NOT prompt user for this parameter. Azure AD group ID (GUID). Required ONLY for groupAssignmentTarget and exclusionGroupAssignmentTarget. Extract from user query or resolve via GetAzureADGroups. Leave empty for allLicensedUsersAssignmentTarget/allDevicesAssignmentTarget.",
                      "x-example": "ed986649-ccfc-4bbb-91a0-acd4fdfd1c70"
                    }
                  }
                },
                "intent": {
                  "type": "string",
                  "enum": ["required", "available", "uninstall"],
                  "description": "REQUIRED: Deployment intent. Extract from context: 'required'/'install'/'deploy'->required, 'available'/'optional'->available, 'uninstall'/'remove'->uninstall. Default: required.",
                  "x-example": "required"
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Assignment created successfully with validated group name"
          },
          "400": {
            "description": "Bad request - invalid assignment data"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Application or group not found"
          }
        }
      }
    },
    "/intune/app-assignments": {
      "get": {
        "operationId": "GetIntuneAppAssignments",
        "summary": "Get App Assignments",
        "description": "UNIFIED app assignment lookup. Supports BOTH direct ID lookup (appId) AND name-based search (appName). Use appId when you have the GUID from a previous call. Use appName for natural language queries like 'who gets Company Portal'. Name search handles multi-platform apps automatically (Windows/Android/iOS/macOS). Provide exactly ONE parameter. Examples: 'assignments for app 189e98a2-5568'->appId=[id]; 'who gets Company Portal'->appName=Company Portal; 'Edge assignments'->appName=Edge.",
        "tags": [
          "Intune Application Management"
        ],
        "parameters": [
          {
            "name": "appId",
            "in": "query",
            "required": false,
            "type": "string",
            "description": "OPTIONAL: Unique Intune application identifier (GUID). Use when you have the appId from a previous API call (e.g., GetIntuneManagedApps). Provide EITHER appId OR appName, not both.",
            "x-example": "189e98a2-5568-437e-94ec-c723b4526794"
          },
          {
            "name": "appName",
            "in": "query",
            "required": false,
            "type": "string",
            "description": "OPTIONAL: App name to search (case-insensitive partial match). Use for natural language queries like 'who gets Company Portal'. Handles multi-platform apps automatically. Provide EITHER appId OR appName, not both.",
            "x-example": "Company Portal"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved application assignments",
            "schema": {
              "type": "object",
              "properties": {
                "lookupType": {
                  "type": "string",
                  "description": "Either 'byId' or 'byName' indicating which parameter was used"
                },
                "appId": {
                  "type": "string",
                  "description": "App ID (for byId lookup)"
                },
                "appName": {
                  "type": "string",
                  "description": "App name (for byId lookup with resolved name)"
                },
                "searchTerm": {
                  "type": "string",
                  "description": "The app name that was searched (for byName lookup)"
                },
                "matchingApps": {
                  "type": "integer",
                  "description": "Number of apps matching the search term (for byName lookup)"
                },
                "appsWithAssignments": {
                  "type": "integer",
                  "description": "Number of matching apps that have assignments (for byName lookup)"
                },
                "totalAssignments": {
                  "type": "integer",
                  "description": "Total number of assignments"
                },
                "assignmentCount": {
                  "type": "integer",
                  "description": "Number of assignments (for byId lookup)"
                },
                "assignments": {
                  "type": "array",
                  "description": "List of assignments with group names resolved (for byId lookup)",
                  "items": {
                    "type": "object"
                  }
                },
                "results": {
                  "type": "array",
                  "description": "Array of matching apps with their assignments (for byName lookup)",
                  "items": {
                    "type": "object",
                    "properties": {
                      "appId": {
                        "type": "string",
                        "description": "Intune app ID"
                      },
                      "appName": {
                        "type": "string",
                        "description": "App display name"
                      },
                      "appType": {
                        "type": "string",
                        "description": "App type (iosStoreApp, androidStoreApp, win32LobApp, etc.)"
                      },
                      "publisher": {
                        "type": "string",
                        "description": "App publisher"
                      },
                      "assignmentCount": {
                        "type": "integer",
                        "description": "Number of assignments for this app"
                      },
                      "assignments": {
                        "type": "array",
                        "description": "List of assignments with group names resolved",
                        "items": {
                          "type": "object"
                        }
                      }
                    }
                  }
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - must provide either appId or appName (not both, not neither)"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Application not found (for appId lookup)"
          }
        }
      }
    },
    "/intune/scripts": {
      "get": {
        "operationId": "GetIntuneScripts",
        "summary": "Get Intune Scripts",
        "description": "UNIFIED script retrieval for ALL platforms. Returns PowerShell (Windows) AND Shell (macOS/Linux) scripts by default. Use platform parameter to filter: 'all' (default - both types), 'windows'/'powershell' (PowerShell only), 'macos'/'linux'/'shell' (Shell only). Each script includes scriptType ('powershell' or 'shell') and platform fields. Use for ALL script queries: 'list scripts', 'show scripts', 'PowerShell scripts', 'macOS scripts', etc. Response includes breakdown of script counts per type. Execute immediately without asking for optional parameters. Examples: 'list scripts'->platform=all (default); 'Windows scripts'->platform=windows; 'macOS scripts'->platform=macos.",
        "tags": [
          "Intune Script Management"
        ],
        "parameters": [
          {
            "name": "scriptPlatform",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Filter by script platform. Values: 'all' (default - returns BOTH PowerShell and Shell scripts), 'windows'/'powershell' (PowerShell only), 'macos'/'linux'/'shell' (Shell scripts only). Extract from user query: 'Windows scripts'->windows, 'macOS scripts'->macos, 'shell scripts'->shell, 'all scripts'/'list scripts'->all (default).",
            "enum": ["all", "windows", "powershell", "macos", "linux", "shell"],
            "default": "all",
            "x-example": "all"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum number of scripts to return (applies after combining both script types). Use top=50 by default. Backend default: 100. Maximum: 200. Only modify if user explicitly says 'show X scripts'.",
            "x-example": 50
          },
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. OData filter for scripts. Use filter=null by default. Only construct filter if user explicitly mentions criteria. Common filters: contains(displayName,'name'), displayName eq 'exact name'. Note: filter is applied separately to each script type.",
            "x-example": "contains(displayName,'Update')"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved unified script list",
            "schema": {
              "type": "object",
              "properties": {
                "scripts": {
                  "type": "array",
                  "description": "Array of script objects (both PowerShell and Shell). Each script includes scriptType ('powershell' or 'shell') and platform ('windows' or 'macos/linux') fields for identification.",
                  "items": {
                    "type": "object"
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Total number of scripts returned"
                },
                "powershellCount": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of PowerShell scripts (Windows)"
                },
                "shellCount": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of Shell scripts (macOS/Linux)"
                },
                "platformFilter": {
                  "type": "string",
                  "description": "The platform filter that was applied"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Response generation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          }
        }
      },
      "post": {
        "operationId": "CreateIntuneScript",
        "summary": "Create PowerShell Script",
        "description": "Creates PowerShell SCRIPT in Intune for automation. Use ONLY when user provides actual PowerShell CODE or asks to create a SCRIPT. Do NOT use for deploying APPLICATIONS - use AddWingetAppToIntune or CreateIntuneLOBApp for apps. Requires displayName and scriptContent (actual PowerShell code).",
        "tags": [
          "Intune Script Management"
        ],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "displayName",
                "scriptContent"
              ],
              "properties": {
                "displayName": {
                  "type": "string",
                  "description": "REQUIRED: Script display name shown in Intune portal. Extract from user message. When user says 'create BitLocker script', use 'BitLocker Script' or similar descriptive name.",
                  "example": "BitLocker Enablement"
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Script description explaining purpose. Extract from user message if provided, otherwise use empty string.",
                  "example": "Enables BitLocker encryption on Windows devices"
                },
                "scriptContent": {
                  "type": "string",
                  "description": "REQUIRED: PowerShell script code as plain text (NOT base64 - API auto-encodes). Extract from user message or code block. Must be valid PowerShell syntax.",
                  "example": "Write-Host 'Hello World'"
                },
                "fileName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Script filename with .ps1 extension. Extract from user message or auto-generate from displayName (e.g., 'My Script' becomes 'My_Script.ps1'). API auto-generates if not provided.",
                  "example": "BitLocker.ps1"
                },
                "runAsAccount": {
                  "type": "string",
                  "enum": ["system", "user"],
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Execution context: 'system' (elevated/admin) or 'user' (current user). Default: 'system'. Extract from user message: 'run as system'->system, 'run as user'->user. Most scripts need system for admin rights.",
                  "example": "system"
                },
                "enforceSignatureCheck": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Require script signature validation. Default: false. Set true only if user mentions 'signed scripts' or 'enforce signature'.",
                  "example": false
                },
                "runAs32Bit": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Run in 32-bit PowerShell on 64-bit systems. Default: false. Set true only if user mentions '32-bit' or 'x86'. Most modern scripts use false (64-bit).",
                  "example": false
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Script created successfully",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Script identifier (GUID)"
                },
                "displayName": {
                  "type": "string",
                  "description": "Script display name"
                },
                "fileName": {
                  "type": "string",
                  "description": "Script file name"
                },
                "createdDateTime": {
                  "type": "string",
                  "description": "Creation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body or missing required fields (displayName, scriptContent)"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "403": {
            "description": "Forbidden - requires DeviceManagementConfiguration.ReadWrite.All"
          }
        }
      }
    },
    "/intune/scripts/{scriptId}": {
      "get": {
        "operationId": "GetIntuneScriptById",
        "summary": "Get Intune Script by ID",
        "description": "Retrieves a single Intune script by ID with full content decoded (readable text). Supports both PowerShell (Windows) and Shell (macOS/Linux) scripts. Returns scriptContentDecoded for human-readable script text, scriptContent for base64-encoded original. Wraps Microsoft Graph API deviceManagement/deviceManagementScripts and deviceShellScripts endpoints with simplified auth via Azure Function keys and managed identity. Use when user asks to get/view/show script content, retrieve script by ID, or see what a script does. Do NOT use for listing all scripts (use GetIntuneScripts instead). CRITICAL: Execute immediately when user provides script ID. Auto-detects script type by trying PowerShell API first, then Shell API. Examples: 'show script abc123'->scriptId=abc123,scriptType=auto; 'get content of PowerShell script xyz'->scriptId=xyz,scriptType=powershell; 'view shell script def456'->scriptId=def456,scriptType=shell.",
        "tags": ["Intune Script Management"],
        "parameters": [
          {
            "name": "scriptId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: The unique identifier (GUID) of the script to retrieve. Extract from user message or previous GetIntuneScripts response. Examples: 'show script 5c325486-xxxx'->scriptId=5c325486-xxxx; 'get content of abc123'->scriptId=abc123."
          },
          {
            "name": "scriptType",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": ["auto", "powershell", "shell"],
            "default": "auto",
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Use 'auto' by default (tries PowerShell first, then Shell). Only specify when user explicitly mentions script type: 'PowerShell script'->powershell; 'shell script'/'bash script'/'macOS script'->shell; no type mentioned->auto."
          }
        ],
        "responses": {
          "200": {
            "description": "Script retrieved successfully with full content",
            "schema": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "Script GUID" },
                "displayName": { "type": "string", "description": "Script display name" },
                "description": { "type": "string", "description": "Script description" },
                "scriptContent": { "type": "string", "description": "Base64-encoded script content" },
                "scriptContentDecoded": { "type": "string", "description": "Decoded script content (readable text)" },
                "scriptType": { "type": "string", "enum": ["powershell", "shell"], "description": "Type of script" },
                "platform": { "type": "string", "enum": ["windows", "macos/linux"], "description": "Target platform" },
                "fileName": { "type": "string", "description": "Script file name" },
                "runAsAccount": { "type": "string", "enum": ["system", "user"], "description": "Execution context" },
                "createdDateTime": { "type": "string", "format": "date-time" },
                "lastModifiedDateTime": { "type": "string", "format": "date-time" }
              }
            }
          },
          "404": {
            "description": "Script not found with the specified ID"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "403": {
            "description": "Forbidden - requires DeviceManagementConfiguration.Read.All"
          }
        }
      }
    },
    "/intune/scripts/{scriptId}/assignments": {
      "get": {
        "operationId": "GetIntuneScriptAssignments",
        "summary": "Get Intune Script Assignments",
        "description": "Retrieves assignment info for PowerShell script showing targeted users/groups/devices. Group names auto-resolved in response (groupDisplayName). Use when user asks who has script access or deployment status. Do NOT use for shell scripts (use GetIntuneShellScriptAssignments). Requires scriptId - if user provides name, first call GetIntuneScripts. Examples: 'who has BitLocker script'->get ID via GetIntuneScripts then call; 'assignments for script 5c325486'->scriptId=[id]. Response shows 'All Devices'/'All Licensed Users' or actual group name.",
        "tags": [
          "Intune Script Management"
        ],
        "parameters": [
          {
            "name": "scriptId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Intune PowerShell script identifier (GUID format). If user provides script name instead of ID, first call GetIntuneScripts to find the script and extract its ID.",
            "x-example": "5c325486-066e-43d5-a389-9e562dcd704a"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved script assignments with enriched group names",
            "schema": {
              "type": "object",
              "properties": {
                "scriptId": {
                  "type": "string",
                  "description": "PowerShell script identifier"
                },
                "assignments": {
                  "type": "array",
                  "description": "Array of assignment objects with enriched group display names",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Assignment identifier"
                      },
                      "target": {
                        "type": "object",
                        "description": "Assignment target with @odata.type and optional groupId"
                      },
                      "groupDisplayName": {
                        "type": "string",
                        "description": "Enriched group name: 'All Devices', 'All Licensed Users', or actual Azure AD group name"
                      }
                    }
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of assignments returned"
                },
                "timestamp": {
                  "type": "string",
                  
                  "description": "ISO 8601 timestamp when request was processed"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid scriptId parameter"
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key"
          },
          "403": {
            "description": "Forbidden - insufficient permissions to read script assignments"
          },
          "404": {
            "description": "Script not found - no PowerShell script exists with the provided ID"
          },
          "500": {
            "description": "Internal server error - check logs for details"
          }
        }
      }
    },
    "/intune/script-assignments/{scriptId}": {
      "post": {
        "operationId": "AssignScript",
        "summary": "Assign Script to Group (Unified)",
        "description": "UNIFIED script assignment that auto-detects script type (PowerShell/Shell) and routes to correct Graph API. Use this instead of AssignIntuneScript or AssignIntuneShellScript. Accepts any script ID - function automatically detects if PowerShell (Windows) or Shell (macOS/Linux). GROUP NOT FOUND HANDLING: If GetAzureADGroups returns empty results for target group, ASK user: 'Group [X] was not found. Would you like me to: a) Create a new group called [X], or b) Search for a similar group name?' If user confirms create->CreateAzureADGroup->then AssignScript. Returns enriched response with script name, type, platform, and group info. runRemediationScript only applies to PowerShell scripts (ignored for Shell). Examples: 'assign BitLocker script to IT group'->resolve IDs then execute; 'deploy Homebrew script to all devices'->auto-detects shell, uses All Devices GUID.",
        "tags": [
          "Intune Script Management"
        ],
        "parameters": [
          {
            "name": "scriptId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Script identifier (GUID). Works with both PowerShell and Shell scripts - type auto-detected.",
            "x-example": "5c325486-066e-43d5-a389-9e562dcd704a"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["targetGroupId"],
              "properties": {
                "targetGroupId": {
                  "type": "string",
                  "description": "REQUIRED: Azure AD group ID (GUID). Special GUID for All Devices: adadadad-808e-44e2-905a-0b7873a8a531.",
                  "x-example": "adadadad-808e-44e2-905a-0b7873a8a531"
                },
                "runRemediationScript": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT prompt user. Run as remediation (PowerShell only, ignored for Shell). Default: false.",
                  "x-example": false
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Assignment created successfully with auto-detected script type",
            "schema": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean",
                  "description": "Operation success status"
                },
                "scriptId": {
                  "type": "string",
                  "description": "Script identifier"
                },
                "scriptDisplayName": {
                  "type": "string",
                  "description": "Script display name from Intune"
                },
                "scriptType": {
                  "type": "string",
                  "description": "Detected script type: 'powershell' or 'shell'"
                },
                "platform": {
                  "type": "string",
                  "description": "Target platform: 'Windows' or 'macOS/Linux'"
                },
                "assignment": {
                  "type": "object",
                  "properties": {
                    "targetGroupId": {
                      "type": "string"
                    },
                    "groupDisplayName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing targetGroupId"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Script or group not found"
          }
        }
      }
    },
    "/intune/script-updates/{scriptId}": {
      "put": {
        "operationId": "UpdateScript",
        "summary": "Update Script (Unified)",
        "description": "UNIFIED script update that auto-detects script type (PowerShell/Shell) and routes to correct Graph API. Use this instead of UpdateIntuneScript or UpdateIntuneShellScript. Accepts any script ID - function automatically detects if PowerShell (Windows) or Shell (macOS/Linux). Validates fileName extension per platform (.ps1 vs .sh). Ignores platform-irrelevant fields (e.g., enforceSignatureCheck for Shell, blockExecution for PowerShell). Returns enriched response with script name, type, platform, and updated fields. Use when user asks to update/modify script without specifying platform. Examples: 'update BitLocker script description'->resolve ID then execute; 'change Homebrew script to run as user'->auto-detects shell, updates runAsAccount.",
        "tags": [
          "Intune Script Management"
        ],
        "parameters": [
          {
            "name": "scriptId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Script identifier (GUID). Works with both PowerShell and Shell scripts - type auto-detected. If user provides script name, first call GetIntuneScripts to find the ID.",
            "x-example": "5c325486-066e-43d5-a389-9e562dcd704a"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "displayName": {
                  "type": "string",
                  "description": "OPTIONAL:  DO NOT prompt user. New display name for the script.",
                  "x-example": "BitLocker Script - Updated"
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL:  DO NOT prompt user. New description for the script.",
                  "x-example": "Updated version with enhanced logging"
                },
                "scriptContent": {
                  "type": "string",
                  "description": "OPTIONAL:  DO NOT prompt user. New script content (plain text - API handles base64 encoding). PowerShell for Windows, Bash for macOS/Linux.",
                  "x-example": "Write-Host 'Updated script'"
                },
                "fileName": {
                  "type": "string",
                  "description": "OPTIONAL:  DO NOT prompt user. New filename. Must match script type (.ps1 for PowerShell, .sh for Shell).",
                  "x-example": "Updated_Script.ps1"
                },
                "runAsAccount": {
                  "type": "string",
                  "enum": ["system", "user"],
                  "description": "OPTIONAL:  DO NOT prompt user. Execution context. Both script types support this.",
                  "x-example": "system"
                },
                "enforceSignatureCheck": {
                  "type": "boolean",
                  "description": "OPTIONAL: DO NOT prompt user. Require signed scripts (PowerShell only, ignored for Shell).",
                  "x-example": false
                },
                "runAs32Bit": {
                  "type": "boolean",
                  "description": "OPTIONAL:  DO NOT prompt user. Run in 32-bit PowerShell (PowerShell only, ignored for Shell).",
                  "x-example": false
                },
                "blockExecution": {
                  "type": "boolean",
                  "description": "OPTIONAL:  DO NOT prompt user. Block script execution (Shell only, ignored for PowerShell).",
                  "x-example": false
                },
                "executionFrequency": {
                  "type": "string",
                  "description": "OPTIONAL: ISO 8601 duration for execution frequency (Shell only, ignored for PowerShell).",
                  "x-example": "PT1H"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Script updated successfully with auto-detected script type",
            "schema": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean",
                  "description": "Operation success status"
                },
                "scriptId": {
                  "type": "string",
                  "description": "Script identifier"
                },
                "scriptDisplayName": {
                  "type": "string",
                  "description": "Script display name (updated if changed)"
                },
                "scriptType": {
                  "type": "string",
                  "description": "Detected script type: 'powershell' or 'shell'"
                },
                "platform": {
                  "type": "string",
                  "description": "Target platform: 'Windows' or 'macOS/Linux'"
                },
                "updatedFields": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "List of fields that were updated"
                },
                "ignoredFields": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "Fields ignored (not applicable for detected script type)"
                },
                "lastModifiedDateTime": {
                  "type": "string",
                  "description": "Last modified timestamp"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid fileName extension or runAsAccount value"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Script not found"
          }
        }
      }
    },
    "/intune/shell-scripts": {
      "post": {
        "operationId": "CreateIntuneShellScript",
        "summary": "Create Intune Shell Script",
        "description": "Creates new shell script (Bash) in Microsoft Intune for automated deployment to macOS and Linux devices. Wraps Microsoft Graph API deviceManagement/deviceShellScripts endpoint with simplified auth via Azure Function keys and managed identity. Use when user asks to create/add/make shell script for macOS or Linux. Do NOT use for PowerShell scripts (use CreateIntuneScript for Windows), updating scripts (use UpdateScript), or listing scripts (use GetIntuneScripts with platform=shell). Requires displayName and scriptContent (plain text Bash code - API handles base64 encoding). Optional parameters with defaults: fileName (auto-generated from displayName with .sh), description (empty string), runAsAccount (system/user, default system). Returns created script with ID for assignment. Execute immediately when user provides script name and code. Examples: 'create macOS update script'->extract displayName and scriptContent, use defaults; 'add Linux monitoring script running as user'->set runAsAccount=user.",
        "tags": [
          "Intune Shell Script Management"
        ],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": [
                "displayName",
                "scriptContent"
              ],
              "properties": {
                "displayName": {
                  "type": "string",
                  "description": "REQUIRED: Shell script display name for Intune console. Extract from user message. When user says 'create Homebrew update script', use displayName='Homebrew Update Script'. Example: 'create macOS maintenance script' -> displayName='macOS Maintenance Script'.",
                  "x-example": "Homebrew Update Script"
                },
                "scriptContent": {
                  "type": "string",
                  "description": "REQUIRED: Shell script (Bash) code as plain text (NOT base64 - API auto-encodes). Extract from user message or code block. Must be valid Bash syntax. Example: '#!/bin/bash\\necho \"Hello from Intune\"' or multi-line script. When user provides code, use it directly.",
                  "x-example": "#!/bin/bash\\n/usr/local/bin/brew update\\n/usr/local/bin/brew upgrade"
                },
                "description": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Shell script description for documentation. Extract from user message if provided, otherwise use empty string. Example: 'Updates Homebrew packages on macOS devices'.",
                  "x-example": "Updates all Homebrew packages to latest versions"
                },
                "fileName": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Script filename with .sh extension. Auto-generate from displayName by replacing spaces with underscores and adding .sh. Example: 'Homebrew Update Script' becomes 'Homebrew_Update_Script.sh'. When user says 'call it update.sh', use fileName='update.sh'.",
                  "x-example": "Homebrew_Update_Script.sh"
                },
                "runAsAccount": {
                  "type": "string",
                  "enum": ["system", "user"],
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Execution context - system or user. Default: system (most scripts need admin rights). Only use user if explicitly mentioned. Example: 'create script running as user' -> runAsAccount='user'. Most macOS/Linux scripts need system for sudo privileges.",
                  "x-example": "system"
                },
                "roleScopeTagIds": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Role scope tag IDs for RBAC. Use default [0] for all devices. Advanced use only. Example: ['0'] for default scope.",
                  "x-example": ["0"]
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Shell script created successfully - returns created script object with id (GUID), displayName, fileName, scriptContent (base64), runAsAccount, createdDateTime, lastModifiedDateTime, and timestamp fields",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Newly created shell script GUID - use this ID for updates, assignments, or retrieval"
                },
                "displayName": {
                  "type": "string",
                  "description": "Shell script display name"
                },
                "fileName": {
                  "type": "string",
                  "description": "Shell script filename (.sh)"
                },
                "createdDateTime": {
                  "type": "string",
                  "description": "Creation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields (displayName and scriptContent are mandatory), invalid JSON format, invalid Bash syntax, or fileName doesn't end with .sh"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "403": {
            "description": "Forbidden - requires DeviceManagementConfiguration.ReadWrite.All permission in Microsoft Graph"
          }
        }
      }
    },
    "/intune/device-analysis": {
      "get": {
        "operationId": "GetDeviceAnalysis",
        "summary": "Complete Device Security Analysis",
        "description": "Comprehensive single-call device security analysis combining: Intune device info (name, OS, encryption, jailbreak status), hardware details (storage, RAM, MAC addresses), compliance status, configuration profile states (succeeded/error/conflict), compliance policy states (pass/fail), assigned apps with install status, installed/detected apps, Defender security data (risk, exposure, health), security alerts (threats, malware), logged-on users (with domain admin flag), vulnerabilities (CVEs with CVSS scores), security recommendations, software inventory (with end-of-support status), Azure AD group memberships, and device action history (wipe, retire, sync). Returns risk scoring (0-100+) with prioritized action items. Use for deep device analysis, security audits, troubleshooting, incident response, or executive summaries. Accepts device name, Azure AD device ID, or user UPN. Execute immediately - provide ONE identifier.",
        "tags": [
          "Intune Device Management"
        ],
        "parameters": [
          {
            "name": "deviceName",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Device name (hostname/computer name) to analyze. Use when user says 'analyze device XYZ' or 'security report for XYZ'. Provide exactly ONE of: deviceName, deviceId, or upn. Example: 'wks-laptop01', 'DESKTOP-ABC123'.",
            "x-example": "wks-laptop01"
          },
          {
            "name": "deviceId",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Azure AD device ID (GUID) to analyze. Use when user provides device ID. Provide exactly ONE of: deviceName, deviceId, or upn. Example: '12345678-1234-1234-1234-123456789abc'.",
            "x-example": "12345678-1234-1234-1234-123456789abc"
          },
          {
            "name": "upn",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. User principal name (UPN) to analyze all devices for that user. Use when user says 'analyze devices for john@contoso.com'. Provide exactly ONE of: deviceName, deviceId, or upn. Example: 'john.doe@contoso.com'.",
            "x-example": "john.doe@contoso.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive device analysis with security data",
            "schema": {
              "type": "object",
              "properties": {
                "device": {
                  "type": "object",
                  "description": "Core device information from Intune",
                  "properties": {
                    "id": { "type": "string", "description": "Intune managed device ID" },
                    "deviceName": { "type": "string", "description": "Device hostname" },
                    "managedDeviceOwnerType": { "type": "string", "description": "company or personal" },
                    "operatingSystem": { "type": "string", "description": "Windows, iOS, Android, macOS" },
                    "osVersion": { "type": "string", "description": "OS version string" },
                    "complianceState": { "type": "string", "description": "compliant, noncompliant, unknown" },
                    "enrolledDateTime": { "type": "string", "format": "date-time" },
                    "lastSyncDateTime": { "type": "string", "format": "date-time" },
                    "userPrincipalName": { "type": "string", "description": "Primary user UPN" },
                    "userDisplayName": { "type": "string", "description": "Primary user display name" },
                    "model": { "type": "string" },
                    "manufacturer": { "type": "string" },
                    "serialNumber": { "type": "string" },
                    "azureADDeviceId": { "type": "string", "description": "Azure AD device object ID" },
                    "azureADRegistered": { "type": "boolean" },
                    "deviceEnrollmentType": { "type": "string" },
                    "managementAgent": { "type": "string", "description": "mdm, eas, etc." },
                    "isEncrypted": { "type": "boolean", "description": "BitLocker/FileVault enabled" },
                    "isSupervised": { "type": "boolean", "description": "iOS supervised mode" },
                    "jailBroken": { "type": "string", "description": "True, False, Unknown" },
                    "deviceRegistrationState": { "type": "string" },
                    "deviceCategory": { "type": "string", "description": "Asset classification category" }
                  }
                },
                "hardware": {
                  "type": "object",
                  "description": "Hardware details",
                  "properties": {
                    "totalStorageSpaceInBytes": { "type": "integer" },
                    "freeStorageSpaceInBytes": { "type": "integer" },
                    "physicalMemoryInBytes": { "type": "integer" },
                    "storageUsedPercent": { "type": "integer", "description": "Percentage of storage used (0-100)" },
                    "storageUsedGB": { "type": "number", "description": "Storage used in GB" },
                    "storageTotalGB": { "type": "number", "description": "Total storage in GB" },
                    "memoryGB": { "type": "number", "description": "RAM in GB" },
                    "wiFiMacAddress": { "type": "string" },
                    "ethernetMacAddress": { "type": "string" },
                    "imei": { "type": "string", "description": "Mobile device IMEI" },
                    "meid": { "type": "string" },
                    "subscriberCarrier": { "type": "string" }
                  }
                },
                "compliance": {
                  "type": "object",
                  "description": "Compliance status details",
                  "properties": {
                    "state": { "type": "string", "description": "compliant, noncompliant, unknown" },
                    "graceperiodExpirationDateTime": { "type": "string", "format": "date-time" },
                    "isCompliant": { "type": "boolean" }
                  }
                },
                "primaryUser": {
                  "type": "object",
                  "description": "Primary user profile details",
                  "properties": {
                    "id": { "type": "string", "description": "Azure AD user ID" },
                    "displayName": { "type": "string" },
                    "userPrincipalName": { "type": "string" },
                    "jobTitle": { "type": "string" },
                    "department": { "type": "string" },
                    "officeLocation": { "type": "string" },
                    "mobilePhone": { "type": "string" },
                    "mail": { "type": "string" },
                    "manager": {
                      "type": "object",
                      "properties": {
                        "displayName": { "type": "string" },
                        "userPrincipalName": { "type": "string" }
                      }
                    }
                  }
                },
                "autopilot": {
                  "type": "object",
                  "description": "Windows Autopilot deployment info",
                  "properties": {
                    "id": { "type": "string" },
                    "groupTag": { "type": "string", "description": "Autopilot group tag for targeting" },
                    "deploymentProfileAssignmentStatus": { "type": "string" },
                    "deploymentProfileAssignedDateTime": { "type": "string", "format": "date-time" },
                    "purchaseOrderIdentifier": { "type": "string" },
                    "addressableUserName": { "type": "string" },
                    "userPrincipalName": { "type": "string" },
                    "enrollmentState": { "type": "string" },
                    "lastContactedDateTime": { "type": "string", "format": "date-time" }
                  }
                },
                "configurationProfiles": {
                  "type": "array",
                  "description": "Configuration profiles assigned with status",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "displayName": { "type": "string" },
                      "state": { "type": "string", "description": "compliant, error, conflict, unknown" },
                      "version": { "type": "integer" },
                      "platformType": { "type": "string" },
                      "settingCount": { "type": "integer" }
                    }
                  }
                },
                "compliancePolicies": {
                  "type": "array",
                  "description": "Compliance policies with status",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "displayName": { "type": "string" },
                      "state": { "type": "string", "description": "compliant, nonCompliant, notApplicable" },
                      "version": { "type": "integer" },
                      "platformType": { "type": "string" },
                      "settingCount": { "type": "integer" }
                    }
                  }
                },
                "assignedApps": {
                  "type": "array",
                  "description": "Apps assigned to device with install status",
                  "items": {
                    "type": "object",
                    "properties": {
                      "appId": { "type": "string" },
                      "displayName": { "type": "string" },
                      "displayVersion": { "type": "string" },
                      "installState": { "type": "string", "description": "installed, failed, notInstalled, pending" },
                      "mobileAppIntent": { "type": "string" }
                    }
                  }
                },
                "installedApps": {
                  "type": "array",
                  "description": "Detected/installed applications",
                  "items": {
                    "type": "object",
                    "properties": {
                      "displayName": { "type": "string" },
                      "version": { "type": "string" },
                      "sizeInByte": { "type": "integer" }
                    }
                  }
                },
                "defender": {
                  "type": "object",
                  "description": "Microsoft Defender for Endpoint status",
                  "properties": {
                    "id": { "type": "string", "description": "Defender machine ID" },
                    "computerDnsName": { "type": "string" },
                    "osPlatform": { "type": "string" },
                    "riskScore": { "type": "string", "description": "None, Informational, Low, Medium, High" },
                    "exposureLevel": { "type": "string", "description": "None, Low, Medium, High" },
                    "healthStatus": { "type": "string", "description": "Active, Inactive, etc." },
                    "onboardingStatus": { "type": "string", "description": "Onboarded, CanBeOnboarded, etc." },
                    "lastSeen": { "type": "string", "format": "date-time" },
                    "lastIpAddress": { "type": "string" }
                  }
                },
                "defenderAlerts": {
                  "type": "array",
                  "description": "Active security alerts from Defender",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "title": { "type": "string" },
                      "severity": { "type": "string", "description": "Low, Medium, High, Critical" },
                      "status": { "type": "string", "description": "New, InProgress, Resolved" },
                      "category": { "type": "string" },
                      "creationTime": { "type": "string", "format": "date-time" },
                      "threatName": { "type": "string" }
                    }
                  }
                },
                "loggedOnUsers": {
                  "type": "array",
                  "description": "Users who have logged onto this device",
                  "items": {
                    "type": "object",
                    "properties": {
                      "accountName": { "type": "string" },
                      "accountDomain": { "type": "string" },
                      "firstSeen": { "type": "string", "format": "date-time" },
                      "lastSeen": { "type": "string", "format": "date-time" },
                      "isDomainAdmin": { "type": "boolean" }
                    }
                  }
                },
                "missingKBs": {
                  "type": "array",
                  "description": "Missing Windows patches/KBs from Defender",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string", "description": "KB article ID" },
                      "name": { "type": "string", "description": "KB name/title" },
                      "osBuild": { "type": "integer", "description": "Applicable OS build number" },
                      "productsNames": { 
                        "type": "array", 
                        "items": { "type": "string" },
                        "description": "Affected product names"
                      },
                      "url": { "type": "string", "description": "KB article URL" },
                      "cveAddressed": { "type": "integer", "description": "Number of CVEs addressed by this KB" }
                    }
                  }
                },
                "vulnerabilities": {
                  "type": "array",
                  "description": "CVE list with severity and CVSS scores",
                  "items": {
                    "type": "object",
                    "properties": {
                      "cveId": { "type": "string", "description": "CVE identifier" },
                      "name": { "type": "string" },
                      "severity": { "type": "string", "description": "Critical, High, Medium, Low" },
                      "cvssScore": { "type": "number", "description": "CVSS v3 score (0-10)" },
                      "description": { "type": "string" },
                      "exploitVerified": { "type": "boolean" }
                    }
                  }
                },
                "recommendations": {
                  "type": "array",
                  "description": "Security recommendations",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "productName": { "type": "string" },
                      "recommendationName": { "type": "string" },
                      "severity": { "type": "integer" },
                      "remediationType": { "type": "string", "description": "Update, ConfigurationChange, etc." },
                      "status": { "type": "string", "description": "Active, Completed" }
                    }
                  }
                },
                "software": {
                  "type": "array",
                  "description": "Software inventory",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "vendor": { "type": "string" },
                      "version": { "type": "string" },
                      "endOfSupportStatus": { "type": "string" }
                    }
                  }
                },
                "groups": {
                  "type": "array",
                  "description": "Azure AD group memberships",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string" },
                      "displayName": { "type": "string" },
                      "description": { "type": "string" }
                    }
                  }
                },
                "deviceActions": {
                  "type": "array",
                  "description": "Recent device actions history",
                  "items": {
                    "type": "object",
                    "properties": {
                      "actionName": { "type": "string", "description": "wipe, retire, sync, etc." },
                      "actionState": { "type": "string" },
                      "startDateTime": { "type": "string", "format": "date-time" },
                      "lastUpdatedDateTime": { "type": "string", "format": "date-time" }
                    }
                  }
                },
                "summary": {
                  "type": "object",
                  "description": "Executive summary with risk scoring",
                  "properties": {
                    "overallRisk": { "type": "string", "description": "Good, Medium, High, Critical" },
                    "riskPoints": { "type": "integer", "description": "Calculated risk score (0-100+)" },
                    "complianceStatus": { "type": "string", "description": "Compliant or Non-Compliant" },
                    "defenderStatus": { "type": "string", "description": "Active, Inactive, Unknown" },
                    "encryptionStatus": { "type": "string", "description": "Encrypted or Not Encrypted" },
                    "vulnerabilityCounts": {
                      "type": "object",
                      "properties": {
                        "critical": { "type": "integer" },
                        "high": { "type": "integer" },
                        "medium": { "type": "integer" },
                        "low": { "type": "integer" }
                      }
                    },
                    "totalVulnerabilities": { "type": "integer" },
                    "totalInstalledApps": { "type": "integer" },
                    "totalAssignedApps": { "type": "integer" },
                    "failedAppInstalls": { "type": "integer" },
                    "totalSoftware": { "type": "integer" },
                    "groupMemberships": { "type": "integer" },
                    "configurationProfiles": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "succeeded": { "type": "integer" },
                        "failed": { "type": "integer" }
                      }
                    },
                    "compliancePolicies": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "compliant": { "type": "integer" },
                        "nonCompliant": { "type": "integer" }
                      }
                    },
                    "activeAlerts": { "type": "integer" },
                    "criticalAlerts": { "type": "integer" },
                    "loggedOnUsers": { "type": "integer" },
                    "missingPatches": { "type": "integer", "description": "Number of missing Windows KBs from Defender" },
                    "autopilotEnabled": { "type": "boolean", "description": "True if device is Autopilot enrolled (Windows only)" },
                    "hasManager": { "type": "boolean", "description": "True if primary user has a manager assigned" },
                    "priorityActions": {
                      "type": "array",
                      "description": "Top priority remediation actions",
                      "items": { "type": "string" }
                    },
                    "analysisComplete": { "type": "boolean", "description": "False if any data fetch failed" }
                  }
                },
                "errors": {
                  "type": "array",
                  "description": "Errors encountered during data collection (partial results still returned)",
                  "items": { "type": "string" }
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Analysis generation timestamp"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - must provide exactly one of: deviceName, deviceId, or upn"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Device not found"
          }
        }
      }
    },
    "/windows/app-search": {
      "get": {
        "operationId": "SearchWindowsApps",
        "summary": "Search Windows Apps (Microsoft Store)",
        "description": "Searches for Windows applications in Microsoft Store. Returns app IDs for AddWingetAppToIntune. IMPORTANT: Only msstore IDs work with Intune. When MULTIPLE apps match, select the best one based on: 1) Exact name match, 2) Official publisher, 3) Most relevant to user intent. If ambiguous, present top 3-5 options to user with name and publisher. Workflow: SearchWindowsApps -> select correct app ID -> AddWingetAppToIntune.",
        "tags": [
          "Windows App Discovery"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "type": "string",
            "required": true,
            "description": "REQUIRED: Search term for app name, publisher, or keyword. Extract from user query.",
            "x-example": "vscode"
          },
          {
            "name": "source",
            "in": "query",
            "type": "string",
            "required": false,
            "default": "msstore",
            "enum": ["all", "winget", "msstore"],
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Default: msstore (recommended for Intune). Only msstore IDs work with AddWingetAppToIntune. WinGet IDs do NOT work - apps stay stuck in processing state.",
            "x-example": "msstore"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 25,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum results to return. Default: 25. Maximum: 100.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved app search results",
            "schema": {
              "type": "object",
              "properties": {
                "results": {
                  "type": "array",
                  "description": "Array of matching applications",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Package identifier (Winget ID or Store Product ID)"
                      },
                      "name": {
                        "type": "string",
                        "description": "Application display name"
                      },
                      "publisher": {
                        "type": "string",
                        "description": "Publisher or developer name"
                      },
                      "version": {
                        "type": "string",
                        "description": "Latest available version"
                      },
                      "source": {
                        "type": "string",
                        "enum": ["winget", "msstore"],
                        "description": "Source repository (winget or msstore)"
                      },
                      "description": {
                        "type": "string",
                        "description": "Short app description"
                      },
                      "storeId": {
                        "type": "string",
                        "description": "Microsoft Store product ID (if available)"
                      }
                    }
                  }
                },
                "count": {
                  "type": "integer",
                  "description": "Number of results returned"
                },
                "query": {
                  "type": "string",
                  "description": "The search query that was used"
                },
                "source": {
                  "type": "string",
                  "description": "The source filter that was applied"
                },
                "breakdown": {
                  "type": "object",
                  "description": "Count breakdown by source",
                  "properties": {
                    "winget": {
                      "type": "integer",
                      "description": "Results from Winget"
                    },
                    "msstore": {
                      "type": "integer",
                      "description": "Results from Microsoft Store"
                    },
                    "merged": {
                      "type": "integer",
                      "description": "Total after deduplication"
                    }
                  }
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing query parameter or invalid source"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/windows/winget-package/{packageId}": {
      "get": {
        "operationId": "GetWingetPackageDetails",
        "summary": "Get WinGet Package Details for Win32 Deployment",
        "description": "Retrieves installer URLs and metadata for WinGet community packages to enable Win32/LOB app deployment in Intune. Returns direct download URLs, SHA256 hashes, silent install switches, and architecture options. WIN32 DEPLOYMENT WORKFLOW: 1) Call this tool to get installerUrl (x64 recommended) and silentInstallSwitch, 2) Download EXE/MSI from installerUrl, 3) Verify SHA256 hash, 4) Package with IntuneWinAppUtil.exe, 5) Upload to Intune as Win32 app using silentInstallSwitch for install command. Use when app isn't in Microsoft Store. Do NOT use for MS Store apps (use AddWingetAppToIntune with alphanumeric IDs). Response includes productCode for detection rules.",
        "tags": [
          "Windows App Discovery"
        ],
        "parameters": [
          {
            "name": "packageId",
            "in": "path",
            "type": "string",
            "required": true,
            "description": "REQUIRED: WinGet package identifier in Publisher.Package format. Get from SearchWindowsApps with source=winget.",
            "x-example": "Publisher.AppName"
          },
          {
            "name": "version",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: Specific version to retrieve. If not provided, returns latest version. Example: 134.0.2",
            "x-example": "134.0.2"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved package details with installer URLs",
            "schema": {
              "type": "object",
              "properties": {
                "packageId": {
                  "type": "string",
                  "description": "WinGet package identifier"
                },
                "version": {
                  "type": "string",
                  "description": "Package version (latest if not specified)"
                },
                "allVersions": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "All available versions in WinGet, sorted newest first. Use to list historical versions or deploy specific older version."
                },
                "totalVersions": {
                  "type": "integer",
                  "description": "Total number of versions available in WinGet repository"
                },
                "name": {
                  "type": "string",
                  "description": "Display name"
                },
                "publisher": {
                  "type": "string",
                  "description": "Publisher name"
                },
                "description": {
                  "type": "string",
                  "description": "Package description"
                },
                "homepage": {
                  "type": "string",
                  "description": "Official website URL"
                },
                "license": {
                  "type": "string",
                  "description": "License type"
                },
                "releaseDate": {
                  "type": "string",
                  "description": "Release date"
                },
                "silentInstallSwitch": {
                  "type": "string",
                  "description": "Command-line switch for silent installation. Use as install command in Win32 app: '{installer.exe} {silentInstallSwitch}'"
                },
                "installers": {
                  "type": "array",
                  "description": "All available installers with download URLs. Choose x64 for most deployments.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "architecture": {
                        "type": "string",
                        "description": "CPU architecture: x64 (recommended), x86, arm64, arm"
                      },
                      "installerType": {
                        "type": "string",
                        "description": "Installer type: exe, msi, wix, msix"
                      },
                      "installerUrl": {
                        "type": "string",
                        "description": "Direct download URL for installer file"
                      },
                      "sha256": {
                        "type": "string",
                        "description": "SHA256 hash for integrity verification"
                      },
                      "productCode": {
                        "type": "string",
                        "description": "Product code for MSI detection rules in Intune"
                      },
                      "scope": {
                        "type": "string",
                        "description": "Install scope: machine (all users) or user"
                      }
                    }
                  }
                },
                "primaryInstallers": {
                  "type": "array",
                  "description": "Common en-US installers (x64, x86, arm64)",
                  "items": {
                    "type": "object",
                    "properties": {
                      "locale": {
                        "type": "string",
                        "description": "Installer locale (e.g., en-US)"
                      },
                      "architecture": {
                        "type": "string",
                        "description": "CPU architecture (x64, x86, arm64)"
                      },
                      "installerType": {
                        "type": "string",
                        "description": "Installer type (exe, msi, msix)"
                      },
                      "installerUrl": {
                        "type": "string",
                        "description": "Direct download URL for installer"
                      },
                      "sha256": {
                        "type": "string",
                        "description": "SHA256 hash of installer file"
                      }
                    }
                  }
                },
                "allInstallersCount": {
                  "type": "integer",
                  "description": "Total number of installers (all locales)"
                },
                "manifestUrl": {
                  "type": "string",
                  "description": "GitHub URL to manifest files"
                },
                "timestamp": {
                  "type": "string",
                  "description": "ISO 8601 timestamp"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid packageId"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Package not found in WinGet repository"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/defender/machines": {
      "get": {
        "operationId": "GetDefenderMachines",
        "summary": "Get Defender Machines",
        "description": "Returns endpoint inventory from Microsoft Defender for Endpoint showing monitored machines (computers, servers, mobile devices). Wraps Defender API machines endpoint with simplified auth. Use when user asks to list, show, or find Defender machines, endpoints, or devices by IP address, health status, risk score, platform, or name. Supports name search via filter=contains(computerDnsName,'WKS-'). Execute immediately without asking for optional parameters. Use defaults (top=25, no filter). For IP-based searches like 'find machine with IP 192.168.1.110', use filter=lastIpAddress eq '192.168.1.110'. For name search use filter=contains(computerDnsName,'DEVICENAME'). IMPORTANT: Do NOT use this endpoint to find machines by software/application installed - use GetDefenderMachinesBySoftware instead. This endpoint cannot filter by software name, vendor, or installed applications.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. OData filter for machines. Use filter=null by default. VALID FILTERS: IP address (lastIpAddress eq '192.168.1.110'), health status (healthStatus eq 'Active'/'Inactive'), risk level (riskScore eq 'High'/'Medium'/'Low'), platform (osPlatform eq 'Windows10'/'Linux'/'macOS'), device name (contains(computerDnsName,'WKS-')). INVALID - DO NOT USE: softwareVendor, softwareName, software, application - these fields do not exist on machines. For software queries use GetDefenderMachinesBySoftware.",
            "x-example": "lastIpAddress eq '192.168.1.110'"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum machines to return. Use top=25 by default for chat interfaces. Backend default: 100. Maximum: 200. Only modify if user explicitly says 'show X machines'. Used for pagination.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved machine list"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          }
        }
      }
    },
    "/defender/software": {
      "get": {
        "operationId": "GetDefenderMachineSoftware",
        "summary": "Get Defender Machine Software",
        "description": "Returns software inventory for specific Defender machine with version details for vulnerability management. Use when user asks for software/applications installed on specific machine. Do NOT use for machine lists (use GetDefenderMachines) or vulnerabilities (use GetDefenderMachineVulnerabilities). Requires machineId - if user provides name instead of ID, first call GetDefenderMachines to get ID. Execute immediately when machineId available. Examples: 'software on machine [id]'->machineId=[id],top=25; 'show 10 apps on [id]'->machineId=[id],top=10. Default: top=25.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "machineId",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Defender machine identifier (GUID format). If user provides machine name instead of ID, first call GetDefenderMachines to find the machine and extract its ID.",
            "x-example": "a1b2c3d4e5f6789012345678901234567890abcd"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum number of software items to return. Extract number from user query or use default. Extraction rules: '5 software'/'show 5'->5, '10 software'/'top 10'->10, NO number specified->25 (default). Always provide a value. Never null. Backend default: 100. Maximum: 200.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved machine software inventory"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Machine not found in Defender - device may not be onboarded. Use GetDefenderMachines with filter=contains(computerDnsName,'NAME') to search."
          }
        }
      }
    },
    "/defender/vulnerabilities": {
      "get": {
        "operationId": "GetDefenderMachineVulnerabilities",
        "summary": "Get Defender Machine Vulnerabilities",
        "description": "Returns security vulnerabilities (CVEs, severity ratings, affected software) for specific Defender machine for risk assessment. Use when user asks for vulnerabilities, security issues, or CVEs on specific machine. Do NOT use for machine lists (use GetDefenderMachines) or software inventory (use GetDefenderMachineSoftware). Requires machineId - if user provides name instead of ID, first call GetDefenderMachines to get ID. Execute immediately when machineId available. Examples: 'vulnerabilities on machine [id]'->machineId=[id],top=25; 'show 10 CVEs on [id]'->machineId=[id],top=10. Default: top=25.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "machineId",
            "in": "query",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Unique Defender machine identifier (GUID format). If user provides machine name instead of ID, first call GetDefenderMachines to find the machine and extract its ID.",
            "x-example": "a1b2c3d4e5f6789012345678901234567890abcd"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum number of vulnerabilities to return. Extract number from user query or use default. Extraction rules: '5 CVEs'/'show 5'->5, '10 vulnerabilities'/'top 10'->10, NO number specified->25 (default). Always provide a value. Never null. Backend default: 100. Maximum: 200.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved machine vulnerabilities"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Machine not found in Defender - device may not be onboarded. Use GetDefenderMachines with filter=contains(computerDnsName,'NAME') to search."
          }
        }
      }
    },
    "/defender/recommendations": {
      "get": {
        "operationId": "GetDefenderRecommendations",
        "summary": "Get Defender Security Recommendations",
        "description": "Retrieves Microsoft Defender for Endpoint security recommendations with remediation actions, affected machines, and risk scoring. Wraps Microsoft Defender API /recommendations endpoint with simplified auth via Azure Function keys and managed identity. Use when user asks to show security recommendations, list vulnerabilities to fix, get threat mitigation advice, or find security improvements. Do NOT use for machine inventory (use GetDefenderMachines), software inventory, or device queries (use GetIntuneDevices). Execute immediately without asking for parameters. Use top=25 and filter=null by default. CRITICAL: Filter properties are severityScore (number 0-10, higher=more critical) and recommendationCategory (not severity/category). Example: 'critical recommendations'->severityScore ge 7; 'application updates'->recommendationCategory eq 'Application'.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. OData filter for recommendations. Use filter=null by default. Supported properties: severityScore (NUMBER 0-10, use ge/le/eq operators: 7-10=Critical, 4-6=High, 1-3=Medium, 0=Low), recommendationCategory eq 'Application'/'OS'/'Network'/'Account', status eq 'Active'/'Resolved', productName, vendor, remediationType eq 'Update'/'ConfigurationChange'/'Uninstall'. Example: severityScore ge 7 and status eq 'Active'. Do NOT use 'severity' or 'category' - use severityScore and recommendationCategory.",
            "x-example": "severityScore ge 7 and status eq 'Active'"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum recommendations to return. Use top=25 by default for chat interfaces. Backend default: 100. Maximum: 200. Only modify if user explicitly says 'show X recommendations'. Used for pagination.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved security recommendations"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          }
        }
      }
    },
    "/defender/vulnerabilities-report": {
      "get": {
        "operationId": "GetDefenderMachineVulnerabilitiesReport",
        "summary": "Get Defender Machine Vulnerabilities Report",
        "description": "Generates consolidated vulnerability report for Defender machines showing all machines with their CVEs, severity ratings, and risk scores in a single call. Use when user asks for vulnerability report, security posture overview, machines with vulnerabilities, or combined machine/CVE analysis. Do NOT use for single machine vulnerabilities (use GetDefenderMachineVulnerabilities) or just machine list (use GetDefenderMachines). Execute immediately without asking for parameters. Examples: 'vulnerability report'->top=25; 'high-risk machines with CVEs'->riskLevel=High; 'show 10 machines with vulnerabilities'->top=10. Returns summary counts (total/critical/high/medium/low vulnerabilities) plus detailed machine-by-machine breakdown.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 25,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum machines to include in report. Use top=25 by default. Maximum: 100. Only modify if user explicitly says 'report for X machines'. Higher values take longer due to per-machine vulnerability fetch.",
            "x-example": 25
          },
          {
            "name": "riskLevel",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Filter machines by risk level. Only set if user explicitly mentions risk. Values: 'High', 'Medium', 'Low', 'None'. Examples: 'high-risk machines'->riskLevel=High, 'vulnerable servers'->riskLevel=null (don't filter). Default: null (all machines).",
            "x-example": "High"
          },
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. OData filter for machines. Advanced filter for specific criteria: osPlatform eq 'Windows10', healthStatus eq 'Active'. Use riskLevel parameter instead for risk-based filtering. Default: null.",
            "x-example": "osPlatform eq 'Windows10'"
          },
          {
            "name": "maxVulnerabilitiesPerMachine",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 10,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum vulnerabilities to fetch per machine. Use 10 by default. Increase for comprehensive reports, decrease for faster response. Maximum: 50.",
            "x-example": 10
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully generated vulnerabilities report with machines and CVEs"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "500": {
            "description": "Internal error - partial report may be available"
          }
        }
      }
    },
    "/defender/machines-by-software": {
      "get": {
        "operationId": "GetDefenderMachinesBySoftware",
        "summary": "Get Machines By Software Installed",
        "description": "Finds all machines that have a specific software product installed. Uses Defender for Endpoint Software API to look up machines by software name and vendor. Use when user asks 'which devices have Firefox installed', 'machines with Chrome', 'devices affected by Adobe Acrobat', or 'computers running Teams'. REQUIRES both softwareName and vendor parameters. Common examples: Firefox (vendor=mozilla), Chrome (vendor=google), Edge (vendor=microsoft), Acrobat (vendor=adobe), Teams (vendor=microsoft), Zoom (vendor=zoom), Docker Desktop (vendor=docker). Returns list of machines with the software including machine ID, DNS name, and OS. Do NOT use GetDefenderMachines with filter for software - that endpoint cannot filter by software. Execute immediately with extracted vendor and product.",
        "tags": [
          "Microsoft Defender for Endpoint"
        ],
        "parameters": [
          {
            "name": "softwareName",
            "in": "query",
            "type": "string",
            "required": true,
            "description": "REQUIRED: Software product name. Extract from user query. Examples: 'Firefox', 'Chrome', 'Edge', 'Teams', 'Zoom', 'Docker Desktop', 'Visual Studio Code', 'Acrobat Reader', 'VLC', '7-Zip'. User says 'devices with Firefox' -> softwareName=firefox. User says 'machines running Chrome' -> softwareName=chrome.",
            "x-example": "firefox"
          },
          {
            "name": "vendor",
            "in": "query",
            "type": "string",
            "required": true,
            "description": "REQUIRED: Software vendor/publisher. Infer from software name if not specified. Common mappings: Firefox->mozilla, Chrome->google, Edge->microsoft, Teams->microsoft, Office->microsoft, Acrobat->adobe, Java->oracle, Zoom->zoom, Slack->slack, Docker->docker, VLC->videolan, 7-Zip->7-zip. User says 'Firefox' -> vendor=mozilla. User says 'Microsoft Teams' -> vendor=microsoft.",
            "x-example": "mozilla"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum machines to return. Use top=100 by default. Only modify if user explicitly says 'show first X machines'.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved machines with the specified software",
            "schema": {
              "type": "object",
              "properties": {
                "machines": {
                  "type": "array",
                  "description": "List of machines with the software installed",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Defender machine ID"
                      },
                      "computerDnsName": {
                        "type": "string",
                        "description": "Machine DNS name"
                      },
                      "osPlatform": {
                        "type": "string",
                        "description": "Operating system platform"
                      }
                    }
                  }
                },
                "count": {
                  "type": "integer",
                  "description": "Number of machines found"
                },
                "softwareId": {
                  "type": "string",
                  "description": "Defender software ID used for lookup (format: vendor-_-product)"
                },
                "softwareName": {
                  "type": "string",
                  "description": "Software name from request"
                },
                "vendor": {
                  "type": "string",
                  "description": "Vendor name from request"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - missing softwareName or vendor parameter"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Software not found in Defender catalog - empty result returned with suggestion"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "HealthCheck",
        "summary": "API Health Check",
        "description": "Performs comprehensive health and connectivity verification for all integrated Microsoft services including Intune and Defender for Endpoint APIs. Essential for troubleshooting service connectivity issues, verifying authentication status, and ensuring optimal system performance.",
        "tags": [
          "System Health"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "All services healthy"
          },
          "503": {
            "description": "One or more services unavailable"
          }
        }
      }
    },
    "/azuread/groups": {
      "get": {
        "operationId": "GetAzureADGroups",
        "summary": "Get Azure AD Groups",
        "description": "Retrieves list of Azure Active Directory groups with support for filtering, searching, pagination, and field selection. Wraps Microsoft Graph API /groups endpoint with simplified authentication via Azure Function keys and managed identity. Returns security groups, Microsoft 365 groups, distribution lists, and mail-enabled security groups. Use when user asks to list, show, find, query, or search for Azure AD groups. Do NOT use for single group lookup by ID (use GetAzureADGroupById instead - to be implemented). Execute immediately without asking for optional parameters. When user requests groups (e.g., 'Show me groups'), use top=100 and filter=null by default. Only construct filter if user explicitly mentions group type, name pattern, or security criteria. For name-based searches, use search parameter with displayName (requires ConsistencyLevel header - handled automatically). Common use case: Finding groups for Intune app/script assignments.",
        "tags": [
          "Azure Active Directory"
        ],
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum groups to return. Use top=100 by default. Maximum: 999. Only modify if user explicitly says 'show X groups'. Used for pagination to limit response size.",
            "x-example": 25
          },
          {
            "name": "filter",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. OData filter for groups. Use filter=null by default. Only construct if user explicitly mentions criteria. Common filters: securityEnabled eq true (security groups only), mailEnabled eq true (mail-enabled), groupTypes/any(c:c eq 'Unified') (Microsoft 365 groups), displayName eq 'ExactName'. Combine with 'and' operator. Use 'search' parameter for name-based queries instead of filter with contains.",
            "x-example": "securityEnabled eq true and mailEnabled eq false"
          },
          {
            "name": "select",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Comma-separated list of properties to include. Default returns: id, displayName, description, groupTypes, securityEnabled, mailEnabled. Useful properties: id, displayName, description, mailNickname, groupTypes, securityEnabled, mailEnabled, createdDateTime.",
            "x-example": "id,displayName,description,groupTypes"
          },
          {
            "name": "search",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Search query for displayName. Use when user says 'find groups like', 'search for groups'. Syntax: provide search term only (e.g., 'Sales'). Automatically sets ConsistencyLevel header. Do NOT use with filter parameter simultaneously.",
            "x-example": "Sales"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved groups list",
            "schema": {
              "type": "object",
              "properties": {
                "groups": {
                  "type": "array",
                  "description": "Array of Azure AD group objects",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Unique group identifier (GUID)"
                      },
                      "displayName": {
                        "type": "string",
                        "description": "Group display name"
                      },
                      "description": {
                        "type": "string",
                        "description": "Group description"
                      },
                      "mailNickname": {
                        "type": "string",
                        "description": "Mail alias"
                      },
                      "securityEnabled": {
                        "type": "boolean",
                        "description": "True if security group"
                      },
                      "mailEnabled": {
                        "type": "boolean",
                        "description": "True if mail-enabled"
                      },
                      "groupTypes": {
                        "type": "array",
                        "description": "Group type indicators (Unified for M365 groups)",
                        "items": {
                          "type": "string"
                        }
                      },
                      "createdDateTime": {
                        "type": "string",
                        "description": "Group creation timestamp in ISO 8601 format"
                      }
                    }
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of groups returned in current response"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Response generation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid filter or search syntax",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Error type"
                },
                "message": {
                  "type": "string",
                  "description": "Detailed error message"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "operationId": "CreateAzureADGroup",
        "summary": "Create Azure AD Group",
        "description": "Creates new Azure Active Directory group (security group or Microsoft 365 group). Wraps Microsoft Graph API POST /groups endpoint with simplified authentication. Requires displayName and mailNickname (must be unique). Defaults to security group (securityEnabled=true, mailEnabled=false) unless specified otherwise. Use when user asks to create, make, add new Azure AD group. Common use case: Creating assignment groups for Intune policies, apps, or scripts. For Microsoft 365 groups, set groupTypes=['Unified'], mailEnabled=true, securityEnabled=false. Execute immediately - displayName and mailNickname are REQUIRED, ask user if not provided. Optional field description can be left empty. Use AddAzureADGroupMember to add members after creation.",
        "tags": [
          "Azure Active Directory"
        ],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "description": "Group creation request body with required displayName and mailNickname",
            "schema": {
              "type": "object",
              "required": [
                "displayName",
                "mailNickname"
              ],
              "properties": {
                "displayName": {
                  "type": "string",
                  "description": "REQUIRED: DO NOT prompt user for this parameter. Group display name visible in Azure AD portal and Intune. Must not be empty. Examples: 'Sales Team', 'Intune-Windows-Users', 'Marketing Department'."
                },
                "mailNickname": {
                  "type": "string",
                  "description": "REQUIRED: DO NOT prompt user for this parameter. Mail alias for the group (must be unique in tenant). No spaces allowed. Usually derived from displayName. Examples: 'SalesTeam', 'IntuneWinUsers', 'MarketingDept'. If user doesn't provide, suggest converting displayName to mailNickname format."
                },
                "description": {
                  "type": "string",
                  "x-ms-visibility": "advanced",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Group description. Leave empty if not provided. Useful for documenting group purpose."
                },
                "securityEnabled": {
                  "type": "boolean",
                  "x-ms-visibility": "advanced",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. True for security group (default), false for distribution group. Default to true for Intune assignment groups.",
                  "default": true
                },
                "mailEnabled": {
                  "type": "boolean",
                  "x-ms-visibility": "advanced",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. True for mail-enabled group, false otherwise (default). Default to false for security groups.",
                  "default": false
                },
                "groupTypes": {
                  "type": "array",
                  "x-ms-visibility": "advanced",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Array indicating group type. Empty array [] for security group (default). ['Unified'] for Microsoft 365 group. Only set to ['Unified'] if user explicitly requests M365 group.",
                  "items": {
                    "type": "string"
                  },
                  "default": []
                },
                "members": {
                  "type": "string",
                  "x-ms-visibility": "advanced",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Comma-separated list of member IDs (device or user GUIDs) to add during group creation. Leave empty to create group without members - use AddAzureADGroupMember to add members later. If user explicitly mentions adding members during creation, resolve device/user names to GUIDs first."
                }
              }
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Group created successfully",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique group identifier (GUID) - use for Intune assignments"
                },
                "displayName": {
                  "type": "string",
                  "description": "Group display name"
                },
                "mailNickname": {
                  "type": "string",
                  "description": "Mail alias"
                },
                "description": {
                  "type": "string",
                  "description": "Group description"
                },
                "createdDateTime": {
                  "type": "string",
                  "description": "Group creation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields or mailNickname already exists",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Error type"
                },
                "message": {
                  "type": "string",
                  "description": "Detailed error message (e.g., 'displayName is required', 'mailNickname already exists')"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/azuread/groups/{groupId}/members": {
      "get": {
        "operationId": "GetAzureADGroupMembers",
        "summary": "Get Azure AD Group Members",
        "description": "Retrieves list of members (users, devices, service principals) from specified Azure AD group. Wraps Microsoft Graph API /groups/{id}/members endpoint with simplified authentication. Returns all directory objects that are direct members of the group. Use when user asks to list, show, get members of a group, or 'who is in this group'. Requires groupId (GUID) - if user provides group name, use GetAzureADGroups with search parameter first to find groupId. Execute immediately without asking for optional parameters. When user requests members, use top=100 by default. Common use case: Verifying Intune assignment group membership before troubleshooting policy/app deployment issues.",
        "tags": [
          "Azure Active Directory"
        ],
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Azure AD group identifier (GUID format). If user provides group name instead of ID, use GetAzureADGroups with search parameter first to retrieve groupId. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'. Must be valid GUID format.",
            "x-example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 100,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Maximum members to return. Use top=100 by default. Maximum: 999. Used for pagination. Only modify if user explicitly says 'show X members'.",
            "x-example": 25
          },
          {
            "name": "select",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Comma-separated list of member properties to include. Default returns: id, displayName, userPrincipalName (for users), deviceId (for devices). Useful properties: id, displayName, userPrincipalName, mail, jobTitle, department.",
            "x-example": "id,displayName,userPrincipalName,mail"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved group members",
            "schema": {
              "type": "object",
              "properties": {
                "members": {
                  "type": "array",
                  "description": "Array of directory objects (users, devices, service principals)",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Member object identifier (GUID)"
                      },
                      "@odata.type": {
                        "type": "string",
                        "description": "Object type (e.g., #microsoft.graph.user, #microsoft.graph.device)"
                      },
                      "displayName": {
                        "type": "string",
                        "description": "Member display name"
                      },
                      "userPrincipalName": {
                        "type": "string",
                        "description": "User principal name (for user objects)"
                      },
                      "mail": {
                        "type": "string",
                        "description": "Email address (if available)"
                      }
                    }
                  }
                },
                "count": {
                  "type": "integer",
                  "format": "int32",
                  "description": "Number of members returned in current response"
                },
                "groupId": {
                  "type": "string",
                  "description": "Group identifier used for the query"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Response generation timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid groupId format (must be GUID)"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Group not found - groupId does not exist. Suggest using GetAzureADGroups to search by name.",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Error type"
                },
                "message": {
                  "type": "string",
                  "description": "Error message with suggestion to use GetAzureADGroups"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "operationId": "AddAzureADGroupMember",
        "summary": "Add Member to Azure AD Group",
        "description": "Adds user or device to Azure AD group. CRITICAL: Intune's azureADDeviceId is NOT the same as Azure AD object id - they are DIFFERENT GUIDs. NEVER use GetIntuneDevices for memberId. REQUIRED workflow: 1) GetAzureADGroups, 2) GetAzureADObject search=[deviceName] type=device (returns correct object id), 3) AddAzureADGroupMember. If 404: used wrong ID type.",
        "tags": [
          "Azure Active Directory"
        ],
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "REQUIRED: Azure AD group identifier (GUID format). If user provides group name, use GetAzureADGroups with search parameter first. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'.",
            "x-example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "description": "Member reference in @odata.id format or simplified memberId format",
            "schema": {
              "type": "object",
              "properties": {
                "memberId": {
                  "type": "string",
                  "description": "REQUIRED: Azure AD object ID (GUID). CRITICAL: Intune azureADDeviceId is NOT Azure AD object id - they are DIFFERENT GUIDs! MUST use GetAzureADObject to get correct id. NEVER use GetIntuneDevices azureActiveDirectoryDeviceId for this field."
                },
                "@odata.id": {
                  "type": "string",
                  "description": "OPTIONAL: DO NOT prompt user for this parameter. Full Microsoft Graph API reference URL. Format: 'https://graph.microsoft.com/v1.0/directoryObjects/{memberId}'. Use memberId field instead (simpler)."
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Member added successfully or already exists in group",
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Success message"
                },
                "groupId": {
                  "type": "string",
                  "description": "Azure AD group ID"
                },
                "memberId": {
                  "type": "string",
                  "description": "Azure AD member object ID"
                },
                "success": {
                  "type": "boolean",
                  "description": "Always true on success"
                },
                "alreadyMember": {
                  "type": "boolean",
                  "description": "True if member was already in group"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing memberId/@odata.id or invalid GUID format",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Error type"
                },
                "message": {
                  "type": "string",
                  "description": "Detailed error message (e.g., 'memberId or @odata.id is required', 'Member already exists')"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "404": {
            "description": "Group or member not found. Error will show which ID failed: groupId if group doesn't exist, memberId if device/user doesn't exist in Azure AD. Common cause: using Intune device id instead of azureActiveDirectoryDeviceId. Use GetAzureADObject to verify member exists.",
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Error type"
                },
                "message": {
                  "type": "string",
                  "description": "Error message with suggestion to verify IDs"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Error timestamp in ISO 8601 format"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/azuread/object": {
      "get": {
        "operationId": "GetAzureADObject",
        "summary": "Get Azure AD Object",
        "description": "Searches Azure AD for devices or users by name and returns their Azure AD object IDs. CRITICAL: Use search parameter with device/user name - NEVER ask for id parameter. Execute immediately with search=[name] type=device. Examples: 'find device WKS-YES11'->search=WKS-YES11 type=device; 'find user john@contoso.com'->search=john@contoso.com type=user. The returned 'id' is the ONLY valid ID for AddAzureADGroupMember memberId. Do NOT confuse with Intune device IDs. For groups use GetAzureADGroups instead.",
        "tags": [
          "Azure Active Directory"
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Extract search term from user message. 'find device WKS-YES11'->search=WKS-YES11; 'find user john@contoso.com'->search=john@contoso.com. Supports partial matching. Use search parameter - do NOT ask for id parameter.",
            "x-example": "WKS-YES11"
          },
          {
            "name": "type",
            "in": "query",
            "type": "string",
            "required": false,
            "enum": ["device", "user"],
            "default": "device",
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Default: device. Values: device, user. Infer from context: device names (WKS-, LAPTOP-, DESKTOP-)-> type=device; email addresses (@)-> type=user.",
            "x-example": "device"
          },
          {
            "name": "id",
            "in": "query",
            "type": "string",
            "required": false,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. IGNORE this parameter unless you already have a GUID. Use search parameter instead for name-based lookups. Only use id for direct GUID lookup when GUID is already known.",
            "x-example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          {
            "name": "top",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 25,
            "description": "OPTIONAL: DO NOT prompt user for this parameter. Default: 25. Maximum objects to return.",
            "x-example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved Azure AD object(s)",
            "schema": {
              "type": "object",
              "properties": {
                "objects": {
                  "type": "array",
                  "description": "Array of Azure AD directory objects (when using search)",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Azure AD object ID (GUID) - USE THIS for AddAzureADGroupMember memberId"
                      },
                      "displayName": {
                        "type": "string",
                        "description": "Object display name"
                      },
                      "type": {
                        "type": "string",
                        "description": "Object type: device, user, or group"
                      },
                      "userPrincipalName": {
                        "type": "string",
                        "description": "User principal name (for user objects)"
                      },
                      "mail": {
                        "type": "string",
                        "description": "Email address (if available)"
                      },
                      "operatingSystem": {
                        "type": "string",
                        "description": "Operating system (for device objects)"
                      }
                    }
                  }
                },
                "object": {
                  "type": "object",
                  "description": "Single Azure AD object (when using id parameter)"
                },
                "count": {
                  "type": "integer",
                  "description": "Number of objects returned"
                },
                "searchType": {
                  "type": "string",
                  "description": "Type of objects searched: device, user, or group"
                },
                "timestamp": {
                  "type": "string",
                  "description": "Response timestamp in ISO 8601 format"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - either search or id parameter is required"
          },
          "401": {
            "description": "Unauthorized - invalid API key"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "definitions": {},
  "parameters": {},
  "responses": {},
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "query",
      "name": "code"
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "tags": [
    {
      "name": "Intune Device Management",
      "description": "Microsoft Intune device inventory and management operations"
    },
    {
      "name": "Intune Compliance",
      "description": "Device compliance monitoring and reporting"
    },
    {
      "name": "Intune Application Management",
      "description": "Application inventory and deployment management"
    },
    {
      "name": "Intune Script Management",
      "description": "PowerShell script creation, management, and deployment for Windows devices"
    },
    {
      "name": "Intune Shell Script Management",
      "description": "Shell script creation, management, and deployment for Linux and macOS devices"
    },
    {
      "name": "Microsoft Defender for Endpoint",
      "description": "Security monitoring and threat management operations"
    },
    {
      "name": "Windows App Discovery",
      "description": "Search and discover Windows applications from Winget and Microsoft Store"
    },
    {
      "name": "System Health",
      "description": "API health monitoring and diagnostics"
    },
    {
      "name": "Azure Active Directory",
      "description": "Azure AD group management and member operations"
    }
  ]
}