diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index 690277cf9..76f4fe191 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (416)
+#define OPENTHREAD_API_VERSION (417)
 
 /**
  * @addtogroup api-instance
diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h
index 9f6bd31a6..d06510383 100644
--- a/include/openthread/platform/radio.h
+++ b/include/openthread/platform/radio.h
@@ -648,6 +648,10 @@ void otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable);
  * If a platform supports `OT_RADIO_CAPS_RX_ON_WHEN_IDLE` it must also support `OT_RADIO_CAPS_CSMA_BACKOFF` and handle
  * idle periods after CCA as described above.
  *
+ * Upon the transition of the "RxOnWhenIdle" flag from TRUE to FALSE, the radio platform should enter sleep mode.
+ * If the radio is currently in receive mode, it should enter sleep mode immediately. Otherwise, it should enter sleep
+ * mode after the current operation is completed.
+ *
  * @param[in]  aInstance    The OpenThread instance structure.
  * @param[in]  aEnable      TRUE to keep radio in Receive state, FALSE to put to Sleep state during idle periods.
  *