diff --git a/include/ur_api.h b/include/ur_api.h
index 6fff45c249..588207bc6e 100644
--- a/include/ur_api.h
+++ b/include/ur_api.h
@@ -847,7 +847,7 @@ urAdapterRetain(
 );
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
@@ -855,6 +855,13 @@ urAdapterRetain(
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///   represents a warning instead. This means that the entry-point call did not
+///   fail. However it might not have behaved as expected.
+///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+///   feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///
diff --git a/scripts/core/adapter.yml b/scripts/core/adapter.yml
index a2331244e1..dbcd9bf5b7 100644
--- a/scripts/core/adapter.yml
+++ b/scripts/core/adapter.yml
@@ -73,12 +73,19 @@ params:
           [in] Adapter handle to retain
 --- #--------------------------------------------------------------------------
 type: function
-desc: "Get the last adapter specific error."
+desc: "Get the last adapter specific warning or error."
 details: |
     To be used after another entry-point has returned
     $X_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
     the circumstances of the underlying driver error and the error code
     returned by the failed driver entry-point.
+  
+    * If `pError` is $X_RESULT_SUCCESS, $X_RESULT_ERROR_ADAPTER_SPECIFIC
+      represents a warning instead. This means that the entry-point call did not
+      fail. However it might not have behaved as expected.
+  
+    * Using $X_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+      feature. Its usage is left at the discretion of adapter maintainers.
 
     * Implementations *must* store the message and error code in thread-local
       storage prior to returning $X_RESULT_ERROR_ADAPTER_SPECIFIC.
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
index de9e029536..692a7e6ae5 100644
--- a/source/loader/ur_libapi.cpp
+++ b/source/loader/ur_libapi.cpp
@@ -353,7 +353,7 @@ ur_result_t UR_APICALL urAdapterRetain(
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
@@ -361,6 +361,13 @@ ur_result_t UR_APICALL urAdapterRetain(
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///   represents a warning instead. This means that the entry-point call did not
+///   fail. However it might not have behaved as expected.
+///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+///   feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
index 85cc45d246..7aa55f4a2b 100644
--- a/source/ur_api.cpp
+++ b/source/ur_api.cpp
@@ -311,7 +311,7 @@ ur_result_t UR_APICALL urAdapterRetain(
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
@@ -319,6 +319,13 @@ ur_result_t UR_APICALL urAdapterRetain(
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///   represents a warning instead. This means that the entry-point call did not
+///   fail. However it might not have behaved as expected.
+///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+///   feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///