diff --git a/api_docs/construct-narrow.md b/api_docs/construct-narrow.md
index a7e3554567..2bb4707274 100644
--- a/api_docs/construct-narrow.md
+++ b/api_docs/construct-narrow.md
@@ -45,6 +45,12 @@ operator, search the current user's personal message history. See
 [searching shared history](/help/search-for-messages#searching-shared-history)
 for details.
 
+Clients should note that the `is:unread` filter takes advantage of the
+fact that there is a database index for unread messages, which can be an
+important optimization when fetching messages in certain cases (e.g.
+when [adding the `read` flag to a user's personal
+messages](/api/update-message-flags-for-narrow)).
+
 **Changes**: In Zulip 7.0 (feature level 177), support was added
 for three filters related to direct messages: `is:dm`, `dm` and
 `dm-including`. The `dm` operator replaced and deprecated the
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 3956102bf4..a221afe11e 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -7043,6 +7043,11 @@ paths:
                     The narrow you want update flags within. See how to
                     [construct a narrow](/api/construct-narrow).
 
+                    Note that, when adding the `read` flag to messages, clients should
+                    consider including a narrow with the `is:unread` filter as an
+                    optimization. Including that filter takes advantage of the fact that
+                    the server has a database index for unread messages.
+
                     **Changes**: In Zulip 7.0 (feature level 177), narrows gained support
                     for three new filters related to direct messages: `is:dm`, `dm` and
                     `dm-including`; replacing and deprecating `is:private`, `pm-with` and