docs: Improve leader_balancer_mode guidance

Update description to help users choose between calibrated, random, and
greedy modes with clearer guidance on when to use each option.

Author: JakeSCahill

docs-data/property-overrides.json

@@ -1297,7 +1297,7 @@
       "config_scope": "cluster"
     },
     "leader_balancer_mode": {
-      "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.",
+      "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.",
       "config_scope": "cluster"
     },
     "leader_balancer_mute_timeout": {

modules/reference/attachments/redpanda-properties-v26.1.2.json

@@ -8700,7 +8700,7 @@
             "config_scope": "cluster",
             "default": "calibrated",
             "defined_in": "src/v/config/configuration.cc",
-            "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.\n* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.\n* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.",
+            "description": "Mode of the leader balancer optimization strategy.\n\nAccepted values:\n\n* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.\n* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.\n* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.\n\nLegacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.",
             "enum": [
                 "calibrated",
                 "random",

modules/reference/partials/properties/cluster-properties.adoc

@@ -8015,7 +8015,6 @@ endif::[]
 
 // end::redpanda-cloud[]
 
-// tag::redpanda-cloud[]
 === iceberg_rest_catalog_aws_credentials_source
 
 *Accepted values*: `aws_instance_metadata`, `azure_aks_oidc_federation`, `azure_vm_instance_metadata`, `config_file`, `gcp_instance_metadata`, `sts`.
@@ -8076,7 +8075,6 @@ endif::[]
 
 |===
 
-// end::redpanda-cloud[]
 
 // tag::redpanda-cloud[]
 === iceberg_rest_catalog_aws_region
@@ -11509,9 +11507,9 @@ Mode of the leader balancer optimization strategy.
 
 Accepted values:
 
-* `calibrated`: Balances leaders based on replica counts per shard using a calibrated heuristic.
-* `random`: Randomly moves leaders to reduce load on heavily-loaded shards.
-* `greedy`: A topic-aware strategy that distributes each topic's leadership evenly across all brokers. Pre-calculates the target distribution for consistent, reproducible results across runs. Useful for benchmarking or production environments where predictable leader distribution matters.
+* `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads.
+* `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn't prioritize high-impact moves. Kept for legacy compatibility.
+* `greedy`: A topic-aware strategy that pre-calculates the entire target distribution before making moves. Each topic is independently balanced across all brokers. Produces deterministic, reproducible results given the same input. Best for benchmarking or environments requiring predictable leader placement. May move more leaders than other modes to reach its target state.
 
 Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`.