diff --git a/rest-api-spec/api/indices.analyze.json b/rest-api-spec/api/indices.analyze.json
index 737dbb1bf23..610c0c86dd3 100644
--- a/rest-api-spec/api/indices.analyze.json
+++ b/rest-api-spec/api/indices.analyze.json
@@ -30,7 +30,7 @@
         },
         "prefer_local": {
           "type" : "boolean",
-          "description" : "Specify whether a local or random replica should be used (default: true)"
+          "description" : "With `true`, specify that a local shard should be used if available, with `false`, use a random shard (default: true)"
         },
         "text": {
           "type" : "string",
diff --git a/rest-api-spec/api/percolate.json b/rest-api-spec/api/percolate.json
index e1c54356201..43dfc3e681d 100644
--- a/rest-api-spec/api/percolate.json
+++ b/rest-api-spec/api/percolate.json
@@ -20,7 +20,7 @@
       "params": {
         "prefer_local": {
           "type" : "boolean",
-          "description" : "Specify whether a local or random replica should be used (default: true)"
+          "description" : "With `true`, specify that a local shard should be used if available, with `false`, use a random shard (default: true)"
         }
       }
     },