diff --git a/docs/plugins/development/creating-classic-plugins.asciidoc b/docs/plugins/development/creating-classic-plugins.asciidoc
index 638af4a1c3d0f..27a65b6cc9116 100644
--- a/docs/plugins/development/creating-classic-plugins.asciidoc
+++ b/docs/plugins/development/creating-classic-plugins.asciidoc
@@ -89,8 +89,14 @@ The entitlements currently implemented and enforced in {es} that are available t
 
 ===== `manage_threads`
 
-Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. In general, setting the name, priority, daemon state and context class loader are things no plugins should do when executing on
-{es} threadpools; however, many 3rd party libraries that support async operations (e.g. Apache HTTP client) need to manage their own threads. In this case it is justifiable to request this entitlement.
+Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`.
+
+[NOTE]
+====
+This entitlement is rarely necessary. Your plugin should use {es} thread pools and executors (see `Plugin#getExecutorBuilders`) instead of creating and managing its own threads. Plugins should avoid modifying thread name, priority, daemon state, and context class loader when executing on ES threadpools.
+
+However, many 3rd party libraries that support async operations, such as the Apache HTTP client, need to create and manage their own threads. In such cases, it makes sense to request this entitlement.
+====
 
 Example:
 ```yaml