diff --git a/docs/reference/api-reference/caveats.md b/docs/reference/api-reference/caveats.md
new file mode 100644
index 000000000..120e15746
--- /dev/null
+++ b/docs/reference/api-reference/caveats.md
@@ -0,0 +1,9 @@
+# Caveats
+
+## Delayed evaluation of annotation
+
+Hamilton works with [PEP-563](https://peps.python.org/pep-0563/), postponed evaluation of annotations.
+That said, it *does* force evaluation of type-hints when building the function graph. So, if you're using
+particularly complex/slow to load python types and expecting delay, know that they will have to be evaluted
+when the driver is instantiated and modules are passed, so Hamilton can inspect the types and build the
+function graph.
diff --git a/docs/reference/api-reference/index.rst b/docs/reference/api-reference/index.rst
index 9f910c5ec..c9421f1a4 100644
--- a/docs/reference/api-reference/index.rst
+++ b/docs/reference/api-reference/index.rst
@@ -10,6 +10,7 @@ API Reference
    graph-adapters
    drivers
    disabling-telemetry
+   caveats
 
 Here lies documentation for the public API you can build on top of.
 
@@ -23,3 +24,5 @@ See :doc:`graph-adapters` for ways to execute Hamilton.
 See :doc:`drivers` for how to call and instantiate a Hamilton dataflow. Right now there are only two!
 
 See :doc:`disabling-telemetry` for how to disable telemetry.
+
+See :doc:`caveats` for implementation details/design decisions that may impact your use of Hamilton.