diff --git a/CHANGES/1645.doc.rst b/CHANGES/1645.doc.rst
new file mode 100644
index 000000000..c093430a2
--- /dev/null
+++ b/CHANGES/1645.doc.rst
@@ -0,0 +1,4 @@
+Added a note in the :meth:`~yarl.URL.with_query` documentation explaining
+that types implementing ``__int__`` (e.g. :class:`~uuid.UUID`) are
+converted to integers, and advising users to cast to :class:`str` when the
+human-readable representation is needed.
diff --git a/docs/api.rst b/docs/api.rst
index 69417bdd5..704befb9b 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -696,6 +696,20 @@ section generates a new :class:`URL` instance.
       Please see :ref:`yarl-bools-support` for the reason why :class:`bool` is not
       supported out-of-the-box.
 
+      .. tip::
+
+         Types that implement :meth:`~object.__int__` (e.g. :class:`~uuid.UUID`)
+         are converted to integers because :class:`int` is preferred over
+         :class:`str` for numeric coercion.  If you need the human-readable
+         representation, cast the value to :class:`str` before passing it:
+
+         .. doctest::
+
+            >>> import uuid
+            >>> uid = uuid.UUID('3199712f-1b78-4420-852b-a73ee09e6a8f')
+            >>> URL('http://example.com/').with_query({'id': str(uid)})
+            URL('http://example.com/?id=3199712f-1b78-4420-852b-a73ee09e6a8f')
+
    .. doctest::
 
       >>> URL('http://example.com/path?a=b').with_query('c=d')