diff --git a/beacon.yaml b/beacon.yaml
index 3c4dba81..8faae63a 100644
--- a/beacon.yaml
+++ b/beacon.yaml
@@ -283,6 +283,7 @@ components:
         - 'Y'
         - 'MT'
     Beacon:
+      description: Metadata describing a beacon instance.
       type: object
       required:
         - id
@@ -350,7 +351,7 @@ components:
             additionalInfoKey1: additionalInfoValue1
             additionalInfoKey2: [ additionalInfoValue2, additionalInfoValue3]
     BeaconAlleleRequest:
-      description: Allele request as interpreted by the beacon.
+      description: Allele request made against the beacon. The allele must be mapped against a sequence in a genome, and a range can be optionally specified.
       type: object
       required:
         - referenceName
@@ -446,6 +447,7 @@ components:
             - MISS
             - NONE
     BeaconAlleleResponse:
+      description: Response to a query for information about an allele, made against the beacon.
       type: object
       required:
         - beaconId
@@ -523,6 +525,7 @@ components:
           example:
             additionalInfoKey: additionalInfoValue
     BeaconDataset:
+      description: A dataset available in the beacon.
       type: object
       required:
         - id
@@ -585,6 +588,7 @@ components:
         dataUseConditions:
           $ref: '#/components/schemas/DataUseConditions'
     BeaconDatasetAlleleResponse:
+      description: Response containing information about an allele in a particular dataset.
       type: object
       required:
         - datasetId
@@ -608,17 +612,17 @@ components:
         variantCount:
           type: integer
           format: int64
-          description: Number of variants matching the allele request in the dataset.
+          description: Number of times the requested allele has been observed in the dataset.
           minimum: 0
         callCount:
           type: integer
           format: int64
-          description: Number of calls matching the allele request in the dataset.
+          description: Total number of calls in the dataset. Missing calls are not included.
           minimum: 0
         sampleCount:
           type: integer
           format: int64
-          description: Number of samples matching the allele request in the dataset
+          description: Number of samples in the dataset where the requested allele is found.
           minimum: 0
         note:
           type: string