API Evangelist conversational phrasing for Azure API Management REST API Tag Description API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Azure API Management REST API Tag Description API
  version: 1.0.0
extends: openapi/microsoft-azure-api-management-apitagdescription-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/tagDescriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List tag descriptions for an API
      effect: read
      questions:
      - What tag descriptions are defined on one of my APIs?
      - Can I see the documentation text attached to each tag used by an API?
      instructions:
      - text: List the tag descriptions for API {apiId} in service {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      - text: Show every tag description in the API's scope.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/tagDescriptions/{tagDescriptionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tag description on an API
      effect: read
      questions:
      - How do I read the description written for one tag on an API?
      - Does a tag on my API have external docs linked?
      instructions:
      - text: Get tag description {tagDescriptionId} from API {apiId} in service {serviceName}.
        slots:
          tagDescriptionId: path.tagDescriptionId
          apiId: path.apiId
          serviceName: path.serviceName
      - text: Show me the API's description for the tag.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/tagDescriptions/{tagDescriptionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Write a tag description for an API
      effect: write
      questions:
      - How do I document what a tag means within a specific API?
      - Can I replace an existing tag description on an API?
      instructions:
      - text: Create tag description {tagDescriptionId} for API {apiId} in service {serviceName}.
        slots:
          tagDescriptionId: path.tagDescriptionId
          apiId: path.apiId
          serviceName: path.serviceName
      - text: Create or replace the API's description of the tag.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/tagDescriptions/{tagDescriptionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag description from an API
      effect: destructive
      questions:
      - Can I remove the description of a tag from an API?
      - Does deleting a tag description remove the tag itself?
      instructions:
      - text: Delete tag description {tagDescriptionId} from API {apiId} in service {serviceName}.
        slots:
          tagDescriptionId: path.tagDescriptionId
          apiId: path.apiId
          serviceName: path.serviceName
      - text: Remove the API-scoped tag description.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/tagDescriptions/{tagDescriptionId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check a tag description's ETag
      effect: read
      questions:
      - How do I get the ETag of a tag description on an API?
      - Can I check that an API has a description for a tag?
      instructions:
      - text: Get the entity state version of tag description {tagDescriptionId} on API {apiId} in service {serviceName}.
        slots:
          tagDescriptionId: path.tagDescriptionId
          apiId: path.apiId
          serviceName: path.serviceName
      - text: Check whether the API has this tag described.
      method: generated
      generated: '2026-10-01'