diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml
index 81a1321b1..e3635b5b4 100644
--- a/introspection/nm-secret-agent.xml
+++ b/introspection/nm-secret-agent.xml
@@ -46,7 +46,9 @@
                     Array of strings of key names in the requested setting for
                     which NetworkManager thinks a secrets may be required,
                     and/or well-known identifiers and data that may be useful
-                    to the client in processing the secrets request. The Agent
+                    to the client in processing the secrets request.  Note that
+                    it's not always possible to determine which secret is
+                    required, so in some cases no hints may be given.  The Agent
                     should return any secrets it has, or that it thinks are
                     required, regardless of what hints NetworkManager sends
                     in this request.
@@ -109,14 +111,17 @@
         <method name="CancelGetSecrets">
             <tp:docstring>
                 Cancel a pending GetSecrets request for secrets of the given
-                connection.  Any matching request should be canceled.
+                connection.  Any GetSecrets request with the same
+                'connection_path' and 'setting_name' that are given in a
+                CancelGetSecrets request should be canceled.
             </tp:docstring>
             <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_cancel_get_secrets"/>
             <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
             <arg name="connection_path" type="o" direction="in">
                 <tp:docstring>
-                    Object path of the connection for which, if secrets are being
-                    requested, the request should be canceled.
+                    Object path of the connection for which, if secrets for
+                    the given 'setting_name' are being requested, the request
+                    should be canceled.
                 </tp:docstring>
             </arg>
             <arg name="setting_name" type="s" direction="in">