diff --git a/src/content/docs/components/openthread.mdx b/src/content/docs/components/openthread.mdx
index 7052d50b22..d3a9e4aa30 100644
--- a/src/content/docs/components/openthread.mdx
+++ b/src/content/docs/components/openthread.mdx
@@ -67,7 +67,7 @@ openthread:
 - **poll_period** (*Optional*, [Time](/guides/configuration-types#config-time)): When Poll_Period is set on an MTD device, the parent router will enqueue any messages and wait for the child to submit a poll data request
 
 > [!NOTE]
-> esphome.ota does not work when poll_period > 0, instead use http_request.ota, timeout and watchdog_timeout need to be tested to find the correct values.  Values greater than 100sec may be required.
+> esphome.ota does not work when poll_period > 0.  Use openthread.pollperiod to set poll_period to 0 before attempting ota.
 
 - **output_power** (*Optional*, integer): The amount of TX power for the Thread 802.15.4 radio in dBm.
   Range depends on the chip variant: ESP32-C5/C6 from ``-15dBm`` to ``20dBm``, ESP32-H2 from ``-24dBm`` to ``20dBm``.
@@ -87,6 +87,26 @@ openthread:
 
 - **tlv** (*Optional*, string): dataset TLVs from the Thread information in Home Assistant
 
+## `openthread.pollperiod` Action
+
+If poll_period > 0, radio is off during idle, otherwise radio is always on.
+
+```yaml
+on_...:
+  then:
+  # Long form turns radio on all the time
+    - openthread.poll_period:
+        poll_period: 0s
+  # Short form turns radio on all the time
+    - openthread.poll_period: 0s
+  # Short form turns radio off when idle
+    - openthread.radio: 5s
+```
+
+### Configuration variables
+
+- **poll_period** (*Optional*, [Time](/guides/configuration-types#config-time)): Set the poll_period on an MTD device.
+
 ## OpenThread Device Type
 
 See [https://openthread.io/guides/thread-primer/node-roles-and-types](https://openthread.io/guides/thread-primer/node-roles-and-types)