diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index 605b1b06..7d8650fe 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -6170,7 +6170,10 @@ paths:
       tags:
       - IP Allowlist
       operationId: getIpAllowlist
-      description: Retrieve the current IP allowlist configuration for the workspace.
+      description: |
+        Retrieve the current IP allowlist configuration for the workspace.
+
+        Requires the `manage_ip_allowlist` OAuth scope.
       responses:
         '200':
           description: Successful response
@@ -6198,6 +6201,13 @@ paths:
                     errors:
                     - code: unauthorized
                       message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                    - code: token_unauthorized
+                      message: Not authorized to access resource
               schema:
                 "$ref": "#/components/schemas/error"
     put:
@@ -6213,6 +6223,12 @@ paths:
       description: |
         Update the IP allowlist configuration for the workspace.
 
+        Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. Sending `null` for a field is the same as omitting it.
+
+        Every non-blank `ip_allowlist` entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 `parameter_invalid` error.
+
+        Requires the `manage_ip_allowlist` OAuth scope.
+
         {% admonition type="warning" name="Lockout Protection" %}
           The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature.
         {% /admonition %}
@@ -6243,6 +6259,13 @@ paths:
                     errors:
                     - code: unauthorized
                       message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                    - code: token_unauthorized
+                      message: Not authorized to access resource
               schema:
                 "$ref": "#/components/schemas/error"
         '422':
@@ -28528,7 +28551,9 @@ paths:
       operationId: listBrands
       description: |
         Retrieves all brands for the workspace, including the default brand.
-        The default brand id always matches the workspace
+        The default brand id always matches the workspace id.
+
+        Requires the `read_brands` OAuth scope.
       parameters:
         - name: Intercom-Version
           in: header
@@ -28566,6 +28591,21 @@ paths:
           description: Unauthorized
           content:
             application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+                    errors:
+                      - code: unauthorized
+                        message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                      - code: token_unauthorized
+                        message: Not authorized to access resource
               schema:
                 $ref: "#/components/schemas/error"
   "/brands/{id}":
@@ -28574,7 +28614,10 @@ paths:
       tags:
         - Brands
       operationId: retrieveBrand
-      description: Fetches a specific brand by its unique identifier
+      description: |
+        Fetches a specific brand by its unique identifier
+
+        Requires the `read_brands` OAuth scope.
       parameters:
         - name: Intercom-Version
           in: header
@@ -28608,6 +28651,21 @@ paths:
           description: Unauthorized
           content:
             application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+                    errors:
+                      - code: unauthorized
+                        message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                      - code: token_unauthorized
+                        message: Not authorized to access resource
               schema:
                 $ref: "#/components/schemas/error"
         '404':
@@ -28622,7 +28680,7 @@ paths:
                     type: error.list
                     request_id: "req_12345"
                     errors:
-                      - code: not_found
+                      - code: brand_not_found
                         message: Brand not found
   "/emails":
     get:
diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml
index c87a7a84..933f959d 100644
--- a/descriptions/2.17/api.intercom.io.yaml
+++ b/descriptions/2.17/api.intercom.io.yaml
@@ -7472,7 +7472,10 @@ paths:
       tags:
       - IP Allowlist
       operationId: getIpAllowlist
-      description: Retrieve the current IP allowlist configuration for the workspace.
+      description: |
+        Retrieve the current IP allowlist configuration for the workspace.
+
+        Requires the `manage_ip_allowlist` OAuth scope.
       responses:
         '200':
           description: Successful response
@@ -7500,6 +7503,13 @@ paths:
                     errors:
                     - code: unauthorized
                       message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                    - code: token_unauthorized
+                      message: Not authorized to access resource
               schema:
                 "$ref": "#/components/schemas/error"
     put:
@@ -7515,6 +7525,12 @@ paths:
       description: |
         Update the IP allowlist configuration for the workspace.
 
+        Both `enabled` and `ip_allowlist` are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. Sending `null` for a field is the same as omitting it.
+
+        Every non-blank `ip_allowlist` entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 `parameter_invalid` error.
+
+        Requires the `manage_ip_allowlist` OAuth scope.
+
         {% admonition type="warning" name="Lockout Protection" %}
           The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature.
         {% /admonition %}
@@ -7545,6 +7561,13 @@ paths:
                     errors:
                     - code: unauthorized
                       message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                    - code: token_unauthorized
+                      message: Not authorized to access resource
               schema:
                 "$ref": "#/components/schemas/error"
         '422':
@@ -25665,7 +25688,9 @@ paths:
       operationId: listBrands
       description: |
         Retrieves all brands for the workspace, including the default brand.
-        The default brand id always matches the workspace
+        The default brand id always matches the workspace id.
+
+        Requires the `read_brands` OAuth scope.
       parameters:
         - name: Intercom-Version
           in: header
@@ -25703,6 +25728,21 @@ paths:
           description: Unauthorized
           content:
             application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+                    errors:
+                      - code: unauthorized
+                        message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                      - code: token_unauthorized
+                        message: Not authorized to access resource
               schema:
                 $ref: "#/components/schemas/error"
   "/brands/{id}":
@@ -25711,7 +25751,10 @@ paths:
       tags:
         - Brands
       operationId: retrieveBrand
-      description: Fetches a specific brand by its unique identifier
+      description: |
+        Fetches a specific brand by its unique identifier
+
+        Requires the `read_brands` OAuth scope.
       parameters:
         - name: Intercom-Version
           in: header
@@ -25745,6 +25788,21 @@ paths:
           description: Unauthorized
           content:
             application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+                    errors:
+                      - code: unauthorized
+                        message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                      - code: token_unauthorized
+                        message: Not authorized to access resource
               schema:
                 $ref: "#/components/schemas/error"
         '404':
@@ -25759,7 +25817,7 @@ paths:
                     type: error.list
                     request_id: "req_12345"
                     errors:
-                      - code: not_found
+                      - code: brand_not_found
                         message: Brand not found
   "/emails":
     get: