diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
index b8051625eef..03ba9a01624 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
@@ -361,10 +361,15 @@ typedef struct {
 /**
  * @brief Defines the GATT authentication request types.
  *
- * This enumeration lists the types of authentication requests that can be made.
- * It corresponds to the `BTA_GATT_AUTH_REQ_xxx` values defined in `bta/bta_gatt_api.h`.
- * The types include options for no authentication, unauthenticated encryption, authenticated encryption,
- * and both signed versions with and without MITM (Man-In-The-Middle) protection.
+ * Used as the `auth_req` argument in GATT client read/write APIs. It specifies the
+ * link security level required before the ATT request is sent, and is independent
+ * of server-side attribute permission flags (`ESP_GATT_PERM_xxx`).
+ *
+ * @note If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start link
+ *       encryption or SMP pairing before the GATT operation. Handle
+ *       `ESP_GAP_BLE_PASSKEY_REQ_EVT` and call `esp_ble_passkey_reply()` if needed.
+ *
+ * Corresponds to the `BTA_GATT_AUTH_REQ_xxx` values defined in `bta/bta_gatt_api.h`.
  */
 typedef enum {
     ESP_GATT_AUTH_REQ_NONE                  = 0, /*!< No authentication required. Corresponds to BTA_GATT_AUTH_REQ_NONE. */
diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
index 9f662b6c97c..65979ba4abf 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
@@ -874,12 +874,14 @@ esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if,
  * @param[in]       value_len  The length of the value to write in bytes
  * @param[in]       value      The value to write
  * @param[in]       write_type The type of Attribute write operation
- * @param[in]       auth_req   Authentication request type
+ * @param[in]       auth_req   Authenticate request type
  *
  * @note
  *      1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`.
  *      2. This function should be called only after the connection has been established.
  *      3. `handle` must be greater than 0.
+ *      4. If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start encryption
+ *         or SMP pairing before sending the ATT write.
  *
  * @return
  *       - ESP_OK: Success