diff --git a/CRM/Utils/Token.php b/CRM/Utils/Token.php
index c40c0da6ab1..a23e9f3313d 100644
--- a/CRM/Utils/Token.php
+++ b/CRM/Utils/Token.php
@@ -1418,6 +1418,15 @@ public static function getMembershipTokenDetails($membershipIDs) {
   /**
    * Replace existing greeting tokens in message/subject.
    *
+   * This function operates by reference, modifying the first parameter. Other
+   * methods for token replacement in this class return the modified string.
+   * This leads to inconsistency in how these methods must be applied.
+   *
+   * @TODO Remove that inconsistency in usage.
+   *
+   * ::replaceContactTokens() may need to be called after this method, to
+   * replace tokens supplied from this method.
+   *
    * @param string $tokenString
    * @param array $contactDetails
    * @param int $contactId