diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml
index e3635b5b4b..48dde703c5 100644
--- a/introspection/nm-secret-agent.xml
+++ b/introspection/nm-secret-agent.xml
@@ -17,7 +17,11 @@
         <method name="GetSecrets">
             <tp:docstring>
                 Retrieve and return stored secrets, if any, or request new
-                secrets from the agent's user.
+                secrets from the agent's user.  If user interaction is allowed
+                and the user enters new secrets, the agent is expected to save
+                the new secrets to persistent storage (if the secret's flags
+                include AGENT_OWNED) as NetworkManager will not send these
+                secrets back to the same agent via a SaveSecrets() call.
             </tp:docstring>
             <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_get_secrets"/>
             <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>