Clarify Tag applied_at/applied_by are only present in tagging operations (#449)

* Clarify applied_at/applied_by are context-dependent on Tag schema

These fields are only present when a tag is returned as part of a
tagging operation (attach/detach/list on a contact/conversation/ticket).
They are not included in direct tag lookups (GET /tags, GET /tags/{id}).

Customers were confused because the Tag docs page showed these fields,
but GET /tags/{id} uses the tag_basic schema which excludes them.

Fixes intercom/intercom#283507

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Nit: use consistent short description for applied_at and applied_by

Both fields now use the same clarification suffix for consistency.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anubhav-intercom

descriptions/0/api.intercom.io.yaml

@@ -26652,12 +26652,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.10/api.intercom.io.yaml

@@ -15982,12 +15982,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.11/api.intercom.io.yaml

@@ -17649,12 +17649,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
       required:

descriptions/2.12/api.intercom.io.yaml

@@ -17373,12 +17373,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.13/api.intercom.io.yaml

@@ -18984,12 +18984,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.14/api.intercom.io.yaml

@@ -20913,12 +20913,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.15/api.intercom.io.yaml

@@ -21772,12 +21772,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.7/api.intercom.io.yaml

@@ -13981,12 +13981,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.8/api.intercom.io.yaml

@@ -14004,12 +14004,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic:

descriptions/2.9/api.intercom.io.yaml

@@ -15358,12 +15358,12 @@ components:
           type: integer
           format: date-time
           nullable: true
-          description: The time when the tag was applied to the object
+          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           example: 1663597223
         applied_by:
           type: object
           nullable: true
-          description: The admin who applied the tag
+          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
           allOf:
             - "$ref": "#/components/schemas/reference"
     tag_basic: