diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc
index 12cb9afd46..964e72c19e 100644
--- a/docs/agent-api.asciidoc
+++ b/docs/agent-api.asciidoc
@@ -194,6 +194,9 @@ If an error is captured,
 the context from the active transaction is used as context for the captured error,
 and any custom context given as the 2nd argument to <<apm-capture-error,`apm.captureError`>> takes precedence and is shallow merged on top.
 
+TIP: Before using custom context, ensure you understand the different types of
+{apm-overview-ref-v}/metadata.html[metadata] that are available.
+
 [[apm-set-tag]]
 ==== `apm.setTag(name, value)`
 
@@ -235,7 +238,14 @@ You can set multiple labels on the same transaction.
 If an error happens during the current transaction,
 it will also get tagged with the same label.
 
-Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <<apm-set-custom-context,`apm.setCustomContext()`>>).
+TIP: Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable
+(as opposed to data set via <<apm-set-custom-context,`apm.setCustomContext()`>>).
+Before using custom labels, ensure you understand the different types of
+{apm-overview-ref-v}/metadata.html[metadata] that are available.
+
+WARNING: Avoid defining too many user-specified labels.
+Defining too many unique fields in an index is a condition that can lead to a
+{ref}/mapping.html#mapping-limit-settings[mapping explosion].
 
 [[apm-add-tags]]
 ==== `apm.addTags({ [name]: value })`
@@ -280,7 +290,14 @@ You can add labels multiple times.
 If an error happens during the current transaction,
 it will also get tagged with the same labels.
 
-Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <<apm-set-custom-context,`apm.setCustomContext()`>>).
+TIP: Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable
+(as opposed to data set via <<apm-set-custom-context,`apm.setCustomContext()`>>).
+Before using custom labels, ensure you understand the different types of
+{apm-overview-ref-v}/metadata.html[metadata] that are available.
+
+WARNING: Avoid defining too many user-specified labels.
+Defining too many unique fields in an index is a condition that can lead to a
+{ref}/mapping.html#mapping-limit-settings[mapping explosion].
 
 [[apm-capture-error]]
 ==== `apm.captureError(error[, options][, callback])`