diff --git a/docs/reference/cluster/delete-desired-balance.asciidoc b/docs/reference/cluster/delete-desired-balance.asciidoc
index 7b89fed881e41..f81dcab011da4 100644
--- a/docs/reference/cluster/delete-desired-balance.asciidoc
+++ b/docs/reference/cluster/delete-desired-balance.asciidoc
@@ -6,9 +6,13 @@
 
 NOTE: {cloud-only}
 
-Resets the desired balance and starts a new computation from the current allocation.
-This API may be used if desired balance computation diverged from the current state
-and is trying to move too many shards.
+Discards the current desired balance and computes a new desired balance starting from the current allocation of shards.
+This can sometimes help {es} find a desired balance which needs fewer shard movements to achieve, especially if the
+cluster has experienced changes so substantial that the current desired balance is no longer optimal without {es} having
+detected that the current desired balance will take more shard movements to achieve than needed. However, this API
+imposes a heavy load on the elected master node and may not always have the expected effect. Calling this API should
+never be necessary. Consider instead <<shards-rebalancing-heuristics,increasing the value of
+`cluster.routing.allocation.balance.threshold`>> to avoid excessive shard movements.
 
 [[delete-desired-balance-request]]
 ==== {api-request-title}