entity_embed.api.php | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/entity_embed.api.php b/entity_embed.api.php
index f420eb8..2132ec8 100644
--- a/entity_embed.api.php
+++ b/entity_embed.api.php
@@ -90,8 +90,16 @@ function hook_ENTITY_TYPE_embed_context_alter(array &$context, \Drupal\Core\Enti
  * Alter the results of an embedded entity build array.
  *
  * This hook is called after the content has been assembled in a structured
- * array and may be used for doing processing which requires that the complete
- * block content structure has been built.
+ * array, but before the structured array is *fully* developed. Only
+ * hook_entity_view_alter() allows you to modify the completely built entity
+ * content structure.
+ *
+ * Note that any alterations made here must update the cacheability metadata in
+ * $build: otherwise alterations made for embedding an entity in a certain view
+ * mode will also affect that entity in that view mode when not embedded.
+ *
+ * It is recommended to NOT use this hook and instead create embedding-specific
+ * view modes.
  *
  * @param array &$build
  *   A renderable array representing the embedded entity content.
@@ -110,6 +118,13 @@ function hook_entity_embed_alter(array &$build, \Drupal\Core\Entity\EntityInterf
 /**
  * Alter the results of the particular embedded entity type build array.
  *
+ * Note that any alterations made here must update the cacheability metadata in
+ * $build: otherwise alterations made for embedding an entity in a certain view
+ * mode will also affect that entity in that view mode when not embedded.
+ *
+ * It is recommended to NOT use this hook and instead create embedding-specific
+ * view modes.
+ *
  * @param array &$build
  *   A renderable array representing the embedded entity content.
  * @param \Drupal\Core\Entity\EntityInterface $entity