diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 28ce88166e84..ded7a57472e5 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -4436,7 +4436,19 @@ os-stop:
 os:scheduler_hints:
   description: |
     The dictionary of data to send to the scheduler. Alternatively, you can specify
-    ``OS-SCH-HNT:scheduler_hints`` as the string.
+    ``OS-SCH-HNT:scheduler_hints`` as the key in the request body.
+
+    There are a few caveats with scheduler hints:
+
+    * The request validation schema is per hint. For example, some require a
+      single string value, and some accept a list of values.
+    * Hints are only used based on the cloud scheduler configuration, which
+      varies per deployment.
+    * Hints are pluggable per deployment, meaning that a cloud can have custom
+      hints which may not be available in another cloud.
+
+    For these reasons, it is important to consult each cloud's user
+    documentation to know what is available for scheduler hints.
   in: body
   required: false
   type: object
diff --git a/nova/api/openstack/compute/schemas/scheduler_hints.py b/nova/api/openstack/compute/schemas/scheduler_hints.py
index 40aa1f31b170..2994d94d52cc 100644
--- a/nova/api/openstack/compute/schemas/scheduler_hints.py
+++ b/nova/api/openstack/compute/schemas/scheduler_hints.py
@@ -39,7 +39,7 @@ _hints = {
             ]
         },
         'same_host': {
-            # NOTE: The value of 'different_host' is the set of server
+            # NOTE: The value of 'same_host' is the set of server
             # uuids where a new server is scheduled on the same host.
             'type': ['string', 'array'],
             'items': parameter_types.server_id