diff --git a/api-specs/api/types/order-search/OrderSearchCustomType.raml b/api-specs/api/types/order-search/OrderSearchCustomType.raml
index 5aefeaae0..0ab83dea7 100644
--- a/api-specs/api/types/order-search/OrderSearchCustomType.raml
+++ b/api-specs/api/types/order-search/OrderSearchCustomType.raml
@@ -1,7 +1,7 @@
 #%RAML 1.0 DataType
 (package): Order
 displayName: OrderSearchCustomType
-description: Possible values for the `customType` property on [query expressions](/../api/projects/order-search#query-expressions) indicating the data type of the `field`.
+description: Possible values for the `customType` property on [simple expressions](/../api/projects/order-search#simple-expressions) indicating the data type of the `field`.
 type: string
 enum:
   - BooleanType
diff --git a/api-specs/api/types/product-search/ProductSearchMatchingVariantEntry.raml b/api-specs/api/types/product-search/ProductSearchMatchingVariantEntry.raml
index ab6eece7f..a018ba45c 100644
--- a/api-specs/api/types/product-search/ProductSearchMatchingVariantEntry.raml
+++ b/api-specs/api/types/product-search/ProductSearchMatchingVariantEntry.raml
@@ -6,7 +6,9 @@ properties:
   id:
     type: number
     format: int32
-    description: Unique identifier of the variant.
+    description: |
+      `id` of the [ProductVariant](ctp:api:type:ProductVariant) that matches the search query.
   sku?:
     type: string
-    description: SKU of the matching variant.
+    description: |
+      `sku` of the ProductVariant that matches the search query.
diff --git a/api-specs/api/types/product-search/ProductSearchMatchingVariants.raml b/api-specs/api/types/product-search/ProductSearchMatchingVariants.raml
index bd9ad2280..e8fac7a75 100644
--- a/api-specs/api/types/product-search/ProductSearchMatchingVariants.raml
+++ b/api-specs/api/types/product-search/ProductSearchMatchingVariants.raml
@@ -5,7 +5,15 @@ type: object
 properties:
   allMatched:
     type: boolean
-    description: Whether the search criteria definitely matches all Variants of the returned Product, like for Product-level fields. Is always `false` for search expressions on Variant-level fields.
+    description: |
+      `true` if all Variants of the returned Product match the search query, or if search query does not specify any expression for a [Product Variant field](/../api/projects/product-search#field-levels).
+
+      `false` if only a subset of the Product Variants match the search query.
+
+      Is always `false` for query expressions on Product Variant fields.
   matchedVariants:
     type: ProductSearchMatchingVariantEntry[]
-    description: The variants matching the search criteria or empty if all matched.
+    description: |
+      Identifiers of the Product Variants that match the search query.
+
+      Empty if all Product Variants of the returned Product match.
diff --git a/api-specs/api/types/product-search/ProductSearchRequest.raml b/api-specs/api/types/product-search/ProductSearchRequest.raml
index 4d5f8c448..e41ca85c4 100644
--- a/api-specs/api/types/product-search/ProductSearchRequest.raml
+++ b/api-specs/api/types/product-search/ProductSearchRequest.raml
@@ -30,7 +30,10 @@ properties:
   markMatchingVariants?:
     type: boolean
     default: false
-    description: The search can return Products where not all Product Variants match the search criteria. If `true`, the response will include a field called `matchingVariants` that contains the `sku` of Product Variants that match the search query. If the query does not specify any variant-level criteria, `matchingVariants` will be null signifying that all Product Variants are a match.
+    description: |
+      If `query` specifies an expression for a Product Variant field,
+      set this to `true` to get additional information for each returned Product about which Product Variants match the search query.
+      For details, see [matching variants](/../api/projects/product-search#matching-variants).
   productProjectionParameters?:
     type: ProductSearchProjectionParams
     (beta): true
diff --git a/api-specs/api/types/product-search/ProductSearchResult.raml b/api-specs/api/types/product-search/ProductSearchResult.raml
index 186c5dba9..66c460807 100644
--- a/api-specs/api/types/product-search/ProductSearchResult.raml
+++ b/api-specs/api/types/product-search/ProductSearchResult.raml
@@ -6,11 +6,16 @@ properties:
   id:
     (identifier): true
     type: string
-    description: Unique identifier of the Product.
+    description: |
+      `id` of the [Product](ctp:api:type:Product) that matches the search query.
+  matchingVariants?:
+    type: ProductSearchMatchingVariants
+    description: |
+      Information about which Product Variants match the search query.
+      Only present if `markMatchingVariants` is set to `true` in the [ProductSearchRequest](ctp:api:type:ProductSearchRequest).
   productProjection?:
     type: ProductProjection
     (beta): true
-    description: Contains Product Projection data for Products matching the `projection` field in the Search Products request.
-  matchingVariants?:
-    type: ProductSearchMatchingVariants
-    description: Describes the variants that matched the search criteria.
+    description: |
+      Projected data of the Product with `id`.
+      Only present if data integration [with Product Projection parameters](/../api/projects/product-search#with-product-projection-parameters) is requested.
diff --git a/api-specs/api/types/search/SearchFieldType.raml b/api-specs/api/types/search/SearchFieldType.raml
index 501f75432..7b2cc8f02 100644
--- a/api-specs/api/types/search/SearchFieldType.raml
+++ b/api-specs/api/types/search/SearchFieldType.raml
@@ -1,7 +1,7 @@
 #%RAML 1.0 DataType
 (package): Search
 displayName: SearchFieldType
-description: Possible values for the `fieldType` property on [query expressions](/../api/search-query-language#query-expressions) indicating the data type of the `field`.
+description: Possible values for the `fieldType` property on [simple expressions](/../api/search-query-language#simple-expressions) indicating the data type of the `field`.
 type: string
 enum:
   - boolean