diff --git a/doc/API.md b/doc/API.md
index 78c22385..9deb5b1e 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -816,6 +816,7 @@ peerStore.addressBook.getMultiaddrsForPeer(peerId)
 
 Set known `multiaddrs` of a given peer. This will replace previously stored multiaddrs, if available.
 Replacing stored multiaddrs might result in losing obtained certified addresses, which is not desirable.
+Consider using `addressBook.add()` if you're not sure this is what you want to do.
 
 `peerStore.addressBook.set(peerId, multiaddrs)`
 
diff --git a/src/peer-store/address-book.js b/src/peer-store/address-book.js
index 9b049aeb..d4c958a8 100644
--- a/src/peer-store/address-book.js
+++ b/src/peer-store/address-book.js
@@ -160,6 +160,7 @@ class AddressBook extends Book {
    * Set known multiaddrs of a provided peer.
    * This will replace previously stored multiaddrs, if available.
    * Replacing stored multiaddrs might result in losing obtained certified addresses.
+   * If you are not sure, it's recommended to use `add` instead.
    * @override
    * @param {PeerId} peerId
    * @param {Array<Multiaddr>} multiaddrs