diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index 67cb82e4e502ee..d412963d31ffd4 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -2876,7 +2876,8 @@ <h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs <var>n</var></co
   This option specifies how long, in seconds, the Bazel server process
   should wait after the last client request, before it exits.  The
   default value is 10800 (3 hours). <code class='flag'>--max_idle_secs=0</code> will cause the
-  Bazel server process to persist indefinitely.
+  Bazel server process to persist indefinitely. <i>NOTE:</i> this flag is only read if Bazel needs
+  to start a new server. Changing this option will not cause the server to restart.
 </p>
 <p>
   This option may be used by scripts that invoke Bazel to ensure that
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
index 5acaa7941a031e..cf0b6a2a0dd3e3 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
@@ -208,8 +208,9 @@ public String getTypeDescription() {
       effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT, OptionEffectTag.LOSES_INCREMENTAL_STATE},
       valueHelp = "<integer>",
       help =
-          "The number of seconds the build server will wait idling before shutting down. Zero "
-              + "means that the server will never shutdown.")
+          "The number of seconds the build server will wait idling before shutting down. Zero"
+              + " means that the server will never shutdown. This is only read on server-startup,"
+              + " changing this option will not cause the server to restart.")
   public int maxIdleSeconds;
 
   @Option(