diff --git a/schemas/2021-05-01/Microsoft.ContainerService.json b/schemas/2021-05-01/Microsoft.ContainerService.json
index 828bd10016..b6c6ddd173 100644
--- a/schemas/2021-05-01/Microsoft.ContainerService.json
+++ b/schemas/2021-05-01/Microsoft.ContainerService.json
@@ -88,7 +88,8 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ]
+          ],
+          "description": "The SKU of a Managed Cluster."
         },
         "tags": {
           "oneOf": [
@@ -182,7 +183,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Default maintenance configuration properties."
+          "description": "Properties used to configure planned maintenance for a Managed Cluster."
         },
         "type": {
           "type": "string",
@@ -245,7 +246,7 @@
       "properties": {
         "maxSurge": {
           "type": "string",
-          "description": "Count or percentage of additional nodes to be added during upgrade. If empty uses AKS default"
+          "description": "This can either be set to an integer (e.g. '5') or a percentage (e.g. '50%'). If a percentage is specified, it is the percentage of the total agent pool size at the time of the upgrade. For percentages, fractional nodes are rounded up. If not specified, the default is 1. For more information, including best practices, see: https://docs.microsoft.com/azure/aks/upgrade-cluster#customize-node-surge-upgrade"
         }
       },
       "description": "Settings for upgrading an agentpool"
@@ -259,15 +260,15 @@
       "properties": {
         "clientId": {
           "type": "string",
-          "description": "The client id of the user assigned identity."
+          "description": "The client ID of the user assigned identity."
         },
         "objectId": {
           "type": "string",
-          "description": "The object id of the user assigned identity."
+          "description": "The object ID of the user assigned identity."
         },
         "resourceId": {
           "type": "string",
-          "description": "The resource id of the user assigned identity."
+          "description": "The resource ID of the user assigned identity."
         }
       }
     },
@@ -357,7 +358,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The load balancer sku for the managed cluster."
+          "description": "The default is 'standard'. See [Azure Load Balancer SKUs](https://docs.microsoft.com/azure/load-balancer/skus) for more information about the differences between load balancer SKUs."
         },
         "networkMode": {
           "oneOf": [
@@ -372,7 +373,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Network mode used for building Kubernetes network."
+          "description": "This cannot be specified if networkPlugin is anything other than 'azure'."
         },
         "networkPlugin": {
           "oneOf": [
@@ -387,7 +388,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Network plugin used for building Kubernetes network."
+          "description": "Network plugin used for building the Kubernetes network."
         },
         "networkPolicy": {
           "oneOf": [
@@ -402,7 +403,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Network policy used for building Kubernetes network."
+          "description": "Network policy used for building the Kubernetes network."
         },
         "outboundType": {
           "oneOf": [
@@ -417,7 +418,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The outbound (egress) routing method."
+          "description": "This can only be set at cluster creation time and cannot be changed later. For more information see [egress outbound type](https://docs.microsoft.com/azure/aks/egress-outboundtype)."
         },
         "podCidr": {
           "oneOf": [
@@ -463,7 +464,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The list of SSH public keys used to authenticate with Linux-based VMs. Only expect one key specified."
+          "description": "The list of SSH public keys used to authenticate with Linux-based VMs. A maximum of 1 key may be specified."
         }
       },
       "required": [
@@ -523,7 +524,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Allowlist of unsafe sysctls or unsafe sysctl patterns (ending in `*`)."
+          "description": "Allowed list of unsafe sysctls or unsafe sysctl patterns (ending in `*`)."
         },
         "containerLogMaxFiles": {
           "oneOf": [
@@ -557,15 +558,15 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Enable CPU CFS quota enforcement for containers that specify CPU limits."
+          "description": "The default is true."
         },
         "cpuCfsQuotaPeriod": {
           "type": "string",
-          "description": "Sets CPU CFS quota period value."
+          "description": "The default is '100ms.' Valid values are a sequence of decimal numbers with an optional fraction and a unit suffix. For example: '300ms', '2h45m'. Supported units are 'ns', 'us', 'ms', 's', 'm', and 'h'."
         },
         "cpuManagerPolicy": {
           "type": "string",
-          "description": "CPU Manager policy to use."
+          "description": "The default is 'none'. See [Kubernetes CPU management policies](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/#cpu-management-policies) for more information. Allowed values are 'none' and 'static'."
         },
         "failSwapOn": {
           "oneOf": [
@@ -587,7 +588,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The percent of disk usage after which image garbage collection is always run."
+          "description": "To disable image garbage collection, set to 100. The default is 85%"
         },
         "imageGcLowThreshold": {
           "oneOf": [
@@ -598,7 +599,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The percent of disk usage before which image garbage collection is never run."
+          "description": "This cannot be set higher than imageGcHighThreshold. The default is 80%"
         },
         "podMaxPids": {
           "oneOf": [
@@ -613,10 +614,10 @@
         },
         "topologyManagerPolicy": {
           "type": "string",
-          "description": "Topology Manager policy to use."
+          "description": "For more information see [Kubernetes Topology Manager](https://kubernetes.io/docs/tasks/administer-cluster/topology-manager). The default is 'none'. Allowed values are 'none', 'best-effort', 'restricted', and 'single-numa-node'."
         }
       },
-      "description": "Kubelet configurations of agent nodes."
+      "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
     },
     "LinuxOSConfig": {
       "type": "object",
@@ -630,7 +631,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "SwapFileSizeMB specifies size in MB of a swap file will be created on each node."
+          "description": "The size in MB of a swap file that will be created on each node."
         },
         "sysctls": {
           "oneOf": [
@@ -645,14 +646,14 @@
         },
         "transparentHugePageDefrag": {
           "type": "string",
-          "description": "Transparent Huge Page defrag configuration."
+          "description": "Valid values are 'always', 'defer', 'defer+madvise', 'madvise' and 'never'. The default is 'madvise'. For more information see [Transparent Hugepages](https://www.kernel.org/doc/html/latest/admin-guide/mm/transhuge.html#admin-guide-transhuge)."
         },
         "transparentHugePageEnabled": {
           "type": "string",
-          "description": "Transparent Huge Page enabled configuration."
+          "description": "Valid values are 'always', 'madvise', and 'never'. The default is 'always'. For more information see [Transparent Hugepages](https://www.kernel.org/doc/html/latest/admin-guide/mm/transhuge.html#admin-guide-transhuge)."
         }
       },
-      "description": "OS configurations of Linux agent nodes."
+      "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
     },
     "MaintenanceConfigurationProperties": {
       "type": "object",
@@ -683,10 +684,10 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Weekday time slots allowed to upgrade."
+          "description": "If two array entries specify the same day of the week, the applied configuration is the union of times in both entries."
         }
       },
-      "description": "Default maintenance configuration properties."
+      "description": "Properties used to configure planned maintenance for a Managed Cluster."
     },
     "ManagedClusterAADProfile": {
       "type": "object",
@@ -703,7 +704,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "AAD group object IDs that will have admin role of the cluster."
+          "description": "The list of AAD group object IDs that will have admin role of the cluster."
         },
         "clientAppID": {
           "type": "string",
@@ -744,7 +745,7 @@
           "description": "The AAD tenant ID to use for authentication. If not specified, will use the tenant of the deployment subscription."
         }
       },
-      "description": "AADProfile specifies attributes for Azure Active Directory integration."
+      "description": "For more details see [managed AAD on AKS](https://docs.microsoft.com/azure/aks/managed-aad)."
     },
     "ManagedClusterAddonProfile": {
       "type": "object",
@@ -796,7 +797,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Availability zones for nodes. Must use VirtualMachineScaleSets AgentPoolType."
+          "description": "The list of Availability zones to use for nodes. This can only be specified if the AgentPoolType property is 'VirtualMachineScaleSets'."
         },
         "count": {
           "oneOf": [
@@ -829,7 +830,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to enable EncryptionAtHost"
+          "description": "This is only supported on certain VM sizes and in certain Azure regions. For more information, see: https://docs.microsoft.com/azure/aks/enable-host-encryption"
         },
         "enableFIPS": {
           "oneOf": [
@@ -840,7 +841,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to use FIPS enabled OS"
+          "description": "See [Add a FIPS-enabled node pool](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#add-a-fips-enabled-node-pool-preview) for more details."
         },
         "enableNodePublicIP": {
           "oneOf": [
@@ -851,7 +852,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Enable public IP for nodes"
+          "description": "Some scenarios may require nodes in a node pool to receive their own dedicated public IP addresses. A common scenario is for gaming workloads, where a console needs to make a direct connection to a cloud virtual machine to minimize hops. For more information see [assigning a public IP per node](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#assign-a-public-ip-per-node-for-your-node-pools). The default is false."
         },
         "enableUltraSSD": {
           "oneOf": [
@@ -880,7 +881,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. Supported values are MIG1g, MIG2g, MIG3g, MIG4g and MIG7g."
+          "description": "GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU."
         },
         "kubeletConfig": {
           "oneOf": [
@@ -891,7 +892,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Kubelet configurations of agent nodes."
+          "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
         },
         "kubeletDiskType": {
           "oneOf": [
@@ -905,8 +906,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "KubeletDiskType determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. Currently allows one value, OS, resulting in Kubelet using the OS disk for data."
+          ]
         },
         "linuxOSConfig": {
           "oneOf": [
@@ -917,7 +917,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "OS configurations of Linux agent nodes."
+          "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
         },
         "maxCount": {
           "oneOf": [
@@ -928,7 +928,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Maximum number of nodes for auto-scaling"
+          "description": "The maximum number of nodes for auto-scaling"
         },
         "maxPods": {
           "oneOf": [
@@ -939,7 +939,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Maximum number of pods that can run on a node."
+          "description": "The maximum number of pods that can run on a node."
         },
         "minCount": {
           "oneOf": [
@@ -950,7 +950,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Minimum number of nodes for auto-scaling"
+          "description": "The minimum number of nodes for auto-scaling"
         },
         "mode": {
           "oneOf": [
@@ -964,8 +964,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "AgentPoolMode represents mode of an agent pool."
+          ]
         },
         "name": {
           "oneOf": [
@@ -977,7 +976,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Unique name of the agent pool profile in the context of the subscription and resource group."
+          "description": "Windows agent pool names must be 6 characters or less."
         },
         "nodeLabels": {
           "oneOf": [
@@ -992,11 +991,11 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Agent pool node labels to be persisted across all nodes in agent pool."
+          "description": "The node labels to be persisted across all nodes in agent pool."
         },
         "nodePublicIPPrefixID": {
           "type": "string",
-          "description": "Public IP Prefix ID. VM nodes use IPs assigned from this Public IP Prefix."
+          "description": "This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/publicIPPrefixes/{publicIPPrefixName}"
         },
         "nodeTaints": {
           "oneOf": [
@@ -1010,11 +1009,11 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Taints added to new nodes during node pool create and scale. For example, key=value:NoSchedule."
+          "description": "The taints added to new nodes during node pool create and scale. For example, key=value:NoSchedule."
         },
         "orchestratorVersion": {
           "type": "string",
-          "description": "Version of orchestrator specified when creating the managed cluster."
+          "description": "As a best practice, you should upgrade all node pools in an AKS cluster to the same Kubernetes version. The node pool version must have the same major version as the control plane. The node pool minor version must be within two minor versions of the control plane version. The node pool version cannot be greater than the control plane version. For more information see [upgrading a node pool](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#upgrade-a-node-pool)."
         },
         "osDiskSizeGB": {
           "oneOf": [
@@ -1027,7 +1026,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "OS Disk Size in GB to be used to specify the disk size for every machine in this master/agent pool. If you specify 0, it will apply the default osDisk size according to the vmSize specified."
+          "description": "OS Disk Size in GB to be used to specify the disk size for every machine in the master/agent pool. If you specify 0, it will apply the default osDisk size according to the vmSize specified."
         },
         "osDiskType": {
           "oneOf": [
@@ -1041,8 +1040,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OS disk type to be used for machines in a given agent pool. Allowed values are 'Ephemeral' and 'Managed'. If unspecified, defaults to 'Ephemeral' when the VM supports ephemeral OS and has a cache disk larger than the requested OSDiskSizeGB. Otherwise, defaults to 'Managed'. May not be changed after creation."
+          ]
         },
         "osSKU": {
           "oneOf": [
@@ -1056,8 +1054,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OsSKU to be used to specify os sku. Choose from Ubuntu(default) and CBLMariner for Linux OSType. Not applicable to Windows OSType."
+          ]
         },
         "osType": {
           "oneOf": [
@@ -1071,12 +1068,11 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OsType to be used to specify os type. Choose from Linux and Windows. Default to Linux."
+          ]
         },
         "podSubnetID": {
           "type": "string",
-          "description": "specifies a subnet's resource id with subscription, resource group, vnet and subnet name"
+          "description": "If omitted, pod IPs are statically assigned on the node subnet (see vnetSubnetID for more details). This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}"
         },
         "proximityPlacementGroupID": {
           "type": "string",
@@ -1095,7 +1091,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "ScaleSetEvictionPolicy to be used to specify eviction policy for Spot virtual machine scale set. Default to Delete."
+          "description": "This cannot be specified unless the scaleSetPriority is 'Spot'. If not specified, the default is 'Delete'."
         },
         "scaleSetPriority": {
           "oneOf": [
@@ -1110,7 +1106,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "ScaleSetPriority to be used to specify virtual machine scale set priority. Default to regular."
+          "description": "The Virtual Machine Scale Set priority. If not specified, the default is 'Regular'."
         },
         "spotMaxPrice": {
           "oneOf": [
@@ -1122,7 +1118,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "SpotMaxPrice to be used to specify the maximum price you are willing to pay in US Dollars. Possible values are any decimal value greater than zero or -1 which indicates default price to be up-to on-demand."
+          "description": "Possible values are any decimal value greater than zero or -1 which indicates the willingness to pay any on-demand price. For more details on spot pricing, see [spot VMs pricing](https://docs.microsoft.com/azure/virtual-machines/spot-vms#pricing)"
         },
         "tags": {
           "oneOf": [
@@ -1137,7 +1133,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Agent pool tags to be persisted on the agent pool virtual machine scale set."
+          "description": "The tags to be persisted on the agent pool virtual machine scale set."
         },
         "type": {
           "oneOf": [
@@ -1151,8 +1147,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "AgentPoolType represents types of an agent pool."
+          ]
         },
         "upgradeSettings": {
           "oneOf": [
@@ -1167,11 +1162,11 @@
         },
         "vmSize": {
           "type": "string",
-          "description": "Size of agent VMs."
+          "description": "VM size availability varies by region. If a node contains insufficient compute resources (memory, cpu, etc) pods might fail to run correctly. For more details on restricted VM sizes, see: https://docs.microsoft.com/azure/aks/quotas-skus-regions"
         },
         "vnetSubnetID": {
           "type": "string",
-          "description": "specifies a subnet's resource id with subscription, resource group, vnet and subnet name"
+          "description": "If this is not specified, a VNET and subnet will be generated and used. If no podSubnetID is specified, this applies to nodes and pods, otherwise it applies to just nodes. This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}"
         }
       },
       "required": [
@@ -1194,7 +1189,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Availability zones for nodes. Must use VirtualMachineScaleSets AgentPoolType."
+          "description": "The list of Availability zones to use for nodes. This can only be specified if the AgentPoolType property is 'VirtualMachineScaleSets'."
         },
         "count": {
           "oneOf": [
@@ -1227,7 +1222,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to enable EncryptionAtHost"
+          "description": "This is only supported on certain VM sizes and in certain Azure regions. For more information, see: https://docs.microsoft.com/azure/aks/enable-host-encryption"
         },
         "enableFIPS": {
           "oneOf": [
@@ -1238,7 +1233,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to use FIPS enabled OS"
+          "description": "See [Add a FIPS-enabled node pool](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#add-a-fips-enabled-node-pool-preview) for more details."
         },
         "enableNodePublicIP": {
           "oneOf": [
@@ -1249,7 +1244,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Enable public IP for nodes"
+          "description": "Some scenarios may require nodes in a node pool to receive their own dedicated public IP addresses. A common scenario is for gaming workloads, where a console needs to make a direct connection to a cloud virtual machine to minimize hops. For more information see [assigning a public IP per node](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#assign-a-public-ip-per-node-for-your-node-pools). The default is false."
         },
         "enableUltraSSD": {
           "oneOf": [
@@ -1278,7 +1273,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. Supported values are MIG1g, MIG2g, MIG3g, MIG4g and MIG7g."
+          "description": "GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU."
         },
         "kubeletConfig": {
           "oneOf": [
@@ -1289,7 +1284,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Kubelet configurations of agent nodes."
+          "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
         },
         "kubeletDiskType": {
           "oneOf": [
@@ -1303,8 +1298,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "KubeletDiskType determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. Currently allows one value, OS, resulting in Kubelet using the OS disk for data."
+          ]
         },
         "linuxOSConfig": {
           "oneOf": [
@@ -1315,7 +1309,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "OS configurations of Linux agent nodes."
+          "description": "See [AKS custom node configuration](https://docs.microsoft.com/azure/aks/custom-node-configuration) for more details."
         },
         "maxCount": {
           "oneOf": [
@@ -1326,7 +1320,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Maximum number of nodes for auto-scaling"
+          "description": "The maximum number of nodes for auto-scaling"
         },
         "maxPods": {
           "oneOf": [
@@ -1337,7 +1331,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Maximum number of pods that can run on a node."
+          "description": "The maximum number of pods that can run on a node."
         },
         "minCount": {
           "oneOf": [
@@ -1348,7 +1342,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Minimum number of nodes for auto-scaling"
+          "description": "The minimum number of nodes for auto-scaling"
         },
         "mode": {
           "oneOf": [
@@ -1362,8 +1356,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "AgentPoolMode represents mode of an agent pool."
+          ]
         },
         "nodeLabels": {
           "oneOf": [
@@ -1378,11 +1371,11 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Agent pool node labels to be persisted across all nodes in agent pool."
+          "description": "The node labels to be persisted across all nodes in agent pool."
         },
         "nodePublicIPPrefixID": {
           "type": "string",
-          "description": "Public IP Prefix ID. VM nodes use IPs assigned from this Public IP Prefix."
+          "description": "This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/publicIPPrefixes/{publicIPPrefixName}"
         },
         "nodeTaints": {
           "oneOf": [
@@ -1396,11 +1389,11 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Taints added to new nodes during node pool create and scale. For example, key=value:NoSchedule."
+          "description": "The taints added to new nodes during node pool create and scale. For example, key=value:NoSchedule."
         },
         "orchestratorVersion": {
           "type": "string",
-          "description": "Version of orchestrator specified when creating the managed cluster."
+          "description": "As a best practice, you should upgrade all node pools in an AKS cluster to the same Kubernetes version. The node pool version must have the same major version as the control plane. The node pool minor version must be within two minor versions of the control plane version. The node pool version cannot be greater than the control plane version. For more information see [upgrading a node pool](https://docs.microsoft.com/azure/aks/use-multiple-node-pools#upgrade-a-node-pool)."
         },
         "osDiskSizeGB": {
           "oneOf": [
@@ -1413,7 +1406,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "OS Disk Size in GB to be used to specify the disk size for every machine in this master/agent pool. If you specify 0, it will apply the default osDisk size according to the vmSize specified."
+          "description": "OS Disk Size in GB to be used to specify the disk size for every machine in the master/agent pool. If you specify 0, it will apply the default osDisk size according to the vmSize specified."
         },
         "osDiskType": {
           "oneOf": [
@@ -1427,8 +1420,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OS disk type to be used for machines in a given agent pool. Allowed values are 'Ephemeral' and 'Managed'. If unspecified, defaults to 'Ephemeral' when the VM supports ephemeral OS and has a cache disk larger than the requested OSDiskSizeGB. Otherwise, defaults to 'Managed'. May not be changed after creation."
+          ]
         },
         "osSKU": {
           "oneOf": [
@@ -1442,8 +1434,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OsSKU to be used to specify os sku. Choose from Ubuntu(default) and CBLMariner for Linux OSType. Not applicable to Windows OSType."
+          ]
         },
         "osType": {
           "oneOf": [
@@ -1457,12 +1448,11 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "OsType to be used to specify os type. Choose from Linux and Windows. Default to Linux."
+          ]
         },
         "podSubnetID": {
           "type": "string",
-          "description": "specifies a subnet's resource id with subscription, resource group, vnet and subnet name"
+          "description": "If omitted, pod IPs are statically assigned on the node subnet (see vnetSubnetID for more details). This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}"
         },
         "proximityPlacementGroupID": {
           "type": "string",
@@ -1481,7 +1471,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "ScaleSetEvictionPolicy to be used to specify eviction policy for Spot virtual machine scale set. Default to Delete."
+          "description": "This cannot be specified unless the scaleSetPriority is 'Spot'. If not specified, the default is 'Delete'."
         },
         "scaleSetPriority": {
           "oneOf": [
@@ -1496,7 +1486,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "ScaleSetPriority to be used to specify virtual machine scale set priority. Default to regular."
+          "description": "The Virtual Machine Scale Set priority. If not specified, the default is 'Regular'."
         },
         "spotMaxPrice": {
           "oneOf": [
@@ -1508,7 +1498,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "SpotMaxPrice to be used to specify the maximum price you are willing to pay in US Dollars. Possible values are any decimal value greater than zero or -1 which indicates default price to be up-to on-demand."
+          "description": "Possible values are any decimal value greater than zero or -1 which indicates the willingness to pay any on-demand price. For more details on spot pricing, see [spot VMs pricing](https://docs.microsoft.com/azure/virtual-machines/spot-vms#pricing)"
         },
         "tags": {
           "oneOf": [
@@ -1523,7 +1513,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Agent pool tags to be persisted on the agent pool virtual machine scale set."
+          "description": "The tags to be persisted on the agent pool virtual machine scale set."
         },
         "type": {
           "oneOf": [
@@ -1537,8 +1527,7 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ],
-          "description": "AgentPoolType represents types of an agent pool."
+          ]
         },
         "upgradeSettings": {
           "oneOf": [
@@ -1553,11 +1542,11 @@
         },
         "vmSize": {
           "type": "string",
-          "description": "Size of agent VMs."
+          "description": "VM size availability varies by region. If a node contains insufficient compute resources (memory, cpu, etc) pods might fail to run correctly. For more details on restricted VM sizes, see: https://docs.microsoft.com/azure/aks/quotas-skus-regions"
         },
         "vnetSubnetID": {
           "type": "string",
-          "description": "specifies a subnet's resource id with subscription, resource group, vnet and subnet name"
+          "description": "If this is not specified, a VNET and subnet will be generated and used. If no podSubnetID is specified, this applies to nodes and pods, otherwise it applies to just nodes. This is of the form: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}"
         }
       },
       "description": "Properties for the container service agent pool profile."
@@ -1577,7 +1566,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Authorized IP Ranges to kubernetes API server."
+          "description": "IP ranges are specified in CIDR format, e.g. 137.117.106.88/29. This feature is not compatible with clusters that use Public IP Per Node, or clusters that are using a Basic Load Balancer. For more information see [API server authorized IP ranges](https://docs.microsoft.com/azure/aks/api-server-authorized-ip-ranges)."
         },
         "enablePrivateCluster": {
           "oneOf": [
@@ -1588,7 +1577,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to create the cluster as a private cluster or not."
+          "description": "For more details, see [Creating a private AKS cluster](https://docs.microsoft.com/azure/aks/private-clusters)."
         },
         "enablePrivateClusterPublicFQDN": {
           "oneOf": [
@@ -1603,7 +1592,7 @@
         },
         "privateDNSZone": {
           "type": "string",
-          "description": "Private dns zone mode for private cluster. "
+          "description": "The default is System. For more details see [configure private DNS zone](https://docs.microsoft.com/azure/aks/private-clusters#configure-private-dns-zone). Allowed values are 'system' and 'none'."
         }
       },
       "description": "Access profile for managed cluster API server."
@@ -1627,7 +1616,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "upgrade channel for auto upgrade."
+          "description": "For more information see [setting the AKS cluster auto-upgrade channel](https://docs.microsoft.com/azure/aks/upgrade-cluster#set-auto-upgrade-channel)."
         }
       },
       "description": "Auto upgrade profile for a managed cluster."
@@ -1637,11 +1626,11 @@
       "properties": {
         "httpProxy": {
           "type": "string",
-          "description": "HTTP proxy server endpoint to use."
+          "description": "The HTTP proxy server endpoint to use."
         },
         "httpsProxy": {
           "type": "string",
-          "description": "HTTPS proxy server endpoint to use."
+          "description": "The HTTPS proxy server endpoint to use."
         },
         "noProxy": {
           "oneOf": [
@@ -1655,14 +1644,14 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Endpoints that should not go through proxy."
+          "description": "The endpoints that should not go through proxy."
         },
         "trustedCa": {
           "type": "string",
           "description": "Alternative CA cert to use for connecting to proxy servers."
         }
       },
-      "description": "Configurations for provisioning the cluster with HTTP proxy servers."
+      "description": "Cluster HTTP proxy configuration."
     },
     "ManagedClusterIdentity": {
       "type": "object",
@@ -1681,7 +1670,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The type of identity used for the managed cluster. Type 'SystemAssigned' will use an implicitly created identity in master components and an auto-created user assigned identity in MC_ resource group in agent nodes. Type 'None' will not use MSI for the managed cluster, service principal will be used instead."
+          "description": "For more information see [use managed identities in AKS](https://docs.microsoft.com/azure/aks/use-managed-identity)."
         },
         "userAssignedIdentities": {
           "oneOf": [
@@ -1696,7 +1685,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The user identity associated with the managed cluster. This identity will be used in control plane and only one user assigned identity is allowed. The user identity dictionary key references will be ARM resource ids in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'."
+          "description": "The keys must be ARM resource IDs in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'."
         }
       },
       "description": "Identity for the managed cluster."
@@ -1716,7 +1705,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Desired number of allocated SNAT ports per VM. Allowed values must be in the range of 0 to 64000 (inclusive). The default value is 0 which results in Azure dynamically allocating ports."
+          "description": "The desired number of allocated SNAT ports per VM. Allowed values are in the range of 0 to 64000 (inclusive). The default value is 0 which results in Azure dynamically allocating ports."
         },
         "effectiveOutboundIPs": {
           "oneOf": [
@@ -1744,7 +1733,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Desired outbound flow idle timeout in minutes. Allowed values must be in the range of 4 to 120 (inclusive). The default value is 30 minutes."
+          "description": "Desired outbound flow idle timeout in minutes. Allowed values are in the range of 4 to 120 (inclusive). The default value is 30 minutes."
         },
         "managedOutboundIPs": {
           "oneOf": [
@@ -1797,7 +1786,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Desired number of outbound IP created/managed by Azure for the cluster load balancer. Allowed values must be in the range of 1 to 100 (inclusive). The default value is 1. "
+          "description": "The desired number of outbound IPs created/managed by Azure for the cluster load balancer. Allowed values must be in the range of 1 to 100 (inclusive). The default value is 1. "
         }
       },
       "description": "Desired managed outbound IPs for the cluster load balancer."
@@ -1847,7 +1836,7 @@
       "properties": {
         "bindingSelector": {
           "type": "string",
-          "description": "Binding selector to use for the AzureIdentityBinding resource."
+          "description": "The binding selector to use for the AzureIdentityBinding resource."
         },
         "identity": {
           "oneOf": [
@@ -1857,33 +1846,35 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ]
+          ],
+          "description": "Details about a user assigned identity."
         },
         "name": {
           "type": "string",
-          "description": "Name of the pod identity."
+          "description": "The name of the pod identity."
         },
         "namespace": {
           "type": "string",
-          "description": "Namespace of the pod identity."
+          "description": "The namespace of the pod identity."
         }
       },
       "required": [
         "identity",
         "name",
         "namespace"
-      ]
+      ],
+      "description": "Details about the pod identity assigned to the Managed Cluster."
     },
     "ManagedClusterPodIdentityException": {
       "type": "object",
       "properties": {
         "name": {
           "type": "string",
-          "description": "Name of the pod identity exception."
+          "description": "The name of the pod identity exception."
         },
         "namespace": {
           "type": "string",
-          "description": "Namespace of the pod identity exception."
+          "description": "The namespace of the pod identity exception."
         },
         "podLabels": {
           "oneOf": [
@@ -1898,14 +1889,15 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Pod labels to match."
+          "description": "The pod labels to match."
         }
       },
       "required": [
         "name",
         "namespace",
         "podLabels"
-      ]
+      ],
+      "description": "See [disable AAD Pod Identity for a specific Pod/Application](https://azure.github.io/aad-pod-identity/docs/configure/application_exception/) for more details."
     },
     "ManagedClusterPodIdentityProfile": {
       "type": "object",
@@ -1919,7 +1911,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Customer consent for enabling AAD pod identity addon in cluster using Kubenet network plugin."
+          "description": "Running in Kubenet is disabled by default due to the security related nature of AAD Pod Identity and the risks of IP spoofing. See [using Kubenet network plugin with AAD Pod Identity](https://docs.microsoft.com/azure/aks/use-azure-ad-pod-identity#using-kubenet-network-plugin-with-azure-active-directory-pod-managed-identities) for more information."
         },
         "enabled": {
           "oneOf": [
@@ -1944,7 +1936,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "User assigned pod identity settings."
+          "description": "The pod identities to use in the cluster."
         },
         "userAssignedIdentityExceptions": {
           "oneOf": [
@@ -1958,9 +1950,10 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "User assigned pod identity exception settings."
+          "description": "The pod identity exceptions to allow."
         }
-      }
+      },
+      "description": "See [use AAD pod identity](https://docs.microsoft.com/azure/aks/use-azure-ad-pod-identity) for more details on pod identity integration."
     },
     "ManagedClusterProperties": {
       "type": "object",
@@ -1974,7 +1967,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "AADProfile specifies attributes for Azure Active Directory integration."
+          "description": "For more details see [managed AAD on AKS](https://docs.microsoft.com/azure/aks/managed-aad)."
         },
         "addonProfiles": {
           "oneOf": [
@@ -1989,7 +1982,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Profile of managed cluster add-on."
+          "description": "The profile of managed cluster add-on."
         },
         "agentPoolProfiles": {
           "oneOf": [
@@ -2003,7 +1996,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Properties of the agent pool."
+          "description": "The agent pool properties."
         },
         "apiServerAccessProfile": {
           "oneOf": [
@@ -2047,15 +2040,15 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "If set to true, getting static credential will be disabled for this cluster. Expected to only be used for AAD clusters."
+          "description": "If set to true, getting static credentials will be disabled for this cluster. This must only be used on Managed Clusters that are AAD enabled. For more details see [disable local accounts](https://docs.microsoft.com/azure/aks/managed-aad#disable-local-accounts-preview)."
         },
         "diskEncryptionSetID": {
           "type": "string",
-          "description": "ResourceId of the disk encryption set to use for enabling encryption at rest."
+          "description": "This is of the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/diskEncryptionSets/{encryptionSetName}'"
         },
         "dnsPrefix": {
           "type": "string",
-          "description": "DNS prefix specified when creating the managed cluster."
+          "description": "This cannot be updated once the Managed Cluster has been created."
         },
         "enablePodSecurityPolicy": {
           "oneOf": [
@@ -2081,7 +2074,7 @@
         },
         "fqdnSubdomain": {
           "type": "string",
-          "description": "FQDN subdomain specified when creating private cluster with custom private dns zone."
+          "description": "This cannot be updated once the Managed Cluster has been created."
         },
         "httpProxyConfig": {
           "oneOf": [
@@ -2092,7 +2085,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Configurations for provisioning the cluster with HTTP proxy servers."
+          "description": "Cluster HTTP proxy configuration."
         },
         "identityProfile": {
           "oneOf": [
@@ -2111,7 +2104,7 @@
         },
         "kubernetesVersion": {
           "type": "string",
-          "description": "Version of Kubernetes specified when creating the managed cluster."
+          "description": "When you upgrade a supported AKS cluster, Kubernetes minor versions cannot be skipped. All upgrades must be performed sequentially by major version number. For example, upgrades between 1.14.x -> 1.15.x or 1.15.x -> 1.16.x are allowed, however 1.14.x -> 1.16.x is not allowed. See [upgrading an AKS cluster](https://docs.microsoft.com/azure/aks/upgrade-cluster) for more details."
         },
         "linuxProfile": {
           "oneOf": [
@@ -2137,7 +2130,7 @@
         },
         "nodeResourceGroup": {
           "type": "string",
-          "description": "Name of the resource group containing agent pool nodes."
+          "description": "The name of the resource group containing agent pool nodes."
         },
         "podIdentityProfile": {
           "oneOf": [
@@ -2147,7 +2140,8 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ]
+          ],
+          "description": "See [use AAD pod identity](https://docs.microsoft.com/azure/aks/use-azure-ad-pod-identity) for more details on pod identity integration."
         },
         "privateLinkResources": {
           "oneOf": [
@@ -2183,7 +2177,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Profile for Windows VMs in the container service cluster."
+          "description": "Profile for Windows VMs in the managed cluster."
         }
       },
       "description": "Properties of the managed cluster."
@@ -2192,7 +2186,8 @@
       "type": "object",
       "properties": {
         "balance-similar-node-groups": {
-          "type": "string"
+          "type": "string",
+          "description": "Valid values are 'true' and 'false'"
         },
         "expander": {
           "oneOf": [
@@ -2208,52 +2203,68 @@
             {
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
-          ]
+          ],
+          "description": "If not specified, the default is 'random'. See [expanders](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#what-are-expanders) for more information."
         },
         "max-empty-bulk-delete": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is 10."
         },
         "max-graceful-termination-sec": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is 600."
         },
         "max-node-provision-time": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '15m'. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "max-total-unready-percentage": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is 45. The maximum is 100 and the minimum is 0."
         },
         "new-pod-scale-up-delay": {
-          "type": "string"
+          "type": "string",
+          "description": "For scenarios like burst/batch scale where you don't want CA to act before the kubernetes scheduler could schedule all the pods, you can tell CA to ignore unscheduled pods before they're a certain age. The default is '0s'. Values must be an integer followed by a unit ('s' for seconds, 'm' for minutes, 'h' for hours, etc)."
         },
         "ok-total-unready-count": {
-          "type": "string"
+          "type": "string",
+          "description": "This must be an integer. The default is 3."
         },
         "scale-down-delay-after-add": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '10m'. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "scale-down-delay-after-delete": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is the scan-interval. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "scale-down-delay-after-failure": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '3m'. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "scale-down-unneeded-time": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '10m'. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "scale-down-unready-time": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '20m'. Values must be an integer followed by an 'm'. No unit of time other than minutes (m) is supported."
         },
         "scale-down-utilization-threshold": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '0.5'."
         },
         "scan-interval": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is '10'. Values must be an integer number of seconds."
         },
         "skip-nodes-with-local-storage": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is true."
         },
         "skip-nodes-with-system-pods": {
-          "type": "string"
+          "type": "string",
+          "description": "The default is true."
         }
       },
       "description": "Parameters to be applied to the cluster-autoscaler when enabled"
@@ -2290,7 +2301,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Name of a managed cluster SKU."
+          "description": "The name of a managed cluster SKU."
         },
         "tier": {
           "oneOf": [
@@ -2305,9 +2316,10 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Tier of a managed cluster SKU."
+          "description": "If not specified, the default is 'Free'. See [uptime SLA](https://docs.microsoft.com/azure/aks/uptime-sla) for more details."
         }
-      }
+      },
+      "description": "The SKU of a Managed Cluster."
     },
     "managedClusters_agentPools_childResource": {
       "type": "object",
@@ -2370,7 +2382,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Default maintenance configuration properties."
+          "description": "Properties used to configure planned maintenance for a Managed Cluster."
         },
         "type": {
           "type": "string",
@@ -2435,7 +2447,7 @@
         },
         "adminUsername": {
           "type": "string",
-          "description": "Specifies the name of the administrator account. <br><br> **restriction:** Cannot end in \".\" <br><br> **Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br><br> **Minimum-length:** 1 character <br><br> **Max-length:** 20 characters"
+          "description": "Specifies the name of the administrator account. <br><br> **Restriction:** Cannot end in \".\" <br><br> **Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br><br> **Minimum-length:** 1 character <br><br> **Max-length:** 20 characters"
         },
         "enableCSIProxy": {
           "oneOf": [
@@ -2446,7 +2458,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "Whether to enable CSI proxy."
+          "description": "For more details on CSI proxy, see the [CSI proxy GitHub repo](https://github.com/kubernetes-csi/csi-proxy)."
         },
         "licenseType": {
           "oneOf": [
@@ -2461,20 +2473,20 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "The licenseType to use for Windows VMs. Windows_Server is used to enable Azure Hybrid User Benefits for Windows VMs."
+          "description": "The license type to use for Windows VMs. See [Azure Hybrid User Benefits](https://azure.microsoft.com/pricing/hybrid-benefit/faq/) for more details."
         }
       },
       "required": [
         "adminUsername"
       ],
-      "description": "Profile for Windows VMs in the container service cluster."
+      "description": "Profile for Windows VMs in the managed cluster."
     },
     "PrivateEndpoint": {
       "type": "object",
       "properties": {
         "id": {
           "type": "string",
-          "description": "The resource Id for private endpoint"
+          "description": "The resource ID of the private endpoint"
         }
       },
       "description": "Private endpoint which a connection belongs to."
@@ -2537,7 +2549,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "RequiredMembers of the resource"
+          "description": "The RequiredMembers of the resource"
         },
         "type": {
           "type": "string",
@@ -2911,7 +2923,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "A day in a week."
+          "description": "The day of the week."
         },
         "hourSlots": {
           "oneOf": [
@@ -2925,7 +2937,7 @@
               "$ref": "https://schema.management.azure.com/schemas/common/definitions.json#/definitions/expression"
             }
           ],
-          "description": "hour slots in a day."
+          "description": "Each integer hour represents a time range beginning at 0m after the hour ending at the next hour (non-inclusive). 0 corresponds to 00:00 UTC, 23 corresponds to 23:00 UTC. Specifying [0, 1] means the 00:00 - 02:00 UTC time range."
         }
       },
       "description": "Time in a week."
@@ -2944,24 +2956,25 @@
           "description": "The start of a time span"
         }
       },
-      "description": "The time span with start and end properties."
+      "description": "For example, between 2021-05-25T13:00:00Z and 2021-05-25T14:00:00Z."
     },
     "UserAssignedIdentity": {
       "type": "object",
       "properties": {
         "clientId": {
           "type": "string",
-          "description": "The client id of the user assigned identity."
+          "description": "The client ID of the user assigned identity."
         },
         "objectId": {
           "type": "string",
-          "description": "The object id of the user assigned identity."
+          "description": "The object ID of the user assigned identity."
         },
         "resourceId": {
           "type": "string",
-          "description": "The resource id of the user assigned identity."
+          "description": "The resource ID of the user assigned identity."
         }
-      }
+      },
+      "description": "Details about a user assigned identity."
     }
   }
 }
\ No newline at end of file