diff --git a/api/client-server/v1/login.yaml b/api/client-server/v1/login.yaml
index e415e798..3d415c29 100644
--- a/api/client-server/v1/login.yaml
+++ b/api/client-server/v1/login.yaml
@@ -115,7 +115,8 @@ paths:
           description: |-
             The refresh token was accepted, and a new access token has been issued.
             The passed refresh token is no longer valid and cannot be used.
-            A new refresh token may have been returned.
+            A new refresh token will have been returned unless some policy does
+            not allow the user to continue to renew their session.
           examples:
             application/json: |-
               {
diff --git a/drafts/macaroons_caveats.rst b/drafts/macaroons_caveats.rst
index 791d217a..c4b6b6a4 100644
--- a/drafts/macaroons_caveats.rst
+++ b/drafts/macaroons_caveats.rst
@@ -1,7 +1,9 @@
 Macaroon Caveats
 ================
 
-Macaroons (http://theory.stanford.edu/~ataly/Papers/macaroons.pdf) are issued by Matrix servers as authorization tokens. Macaroons may be restricted by adding caveats to them.
+`Macaroons`_ are issued by Matrix servers as authorization tokens. Macaroons may be restricted by adding caveats to them.
+
+.. _Macaroons: http://theory.stanford.edu/~ataly/Papers/macaroons.pdf)
 
 Caveats can only be used for reducing the scope of a token, never for increasing it. Servers are required to reject any macroon with a caveat that they do not understand.