diff --git a/docs/WASI-api.md b/docs/WASI-api.md
index f40899af15..a89cb963d6 100644
--- a/docs/WASI-api.md
+++ b/docs/WASI-api.md
@@ -744,6 +744,12 @@ Inputs:
 
 Open a file or directory.
 
+The returned file descriptor is not guaranteed to be the lowest-numbered
+file descriptor not currently open; it is randomized to prevent
+applications from depending on making assumptions about indexes, since
+this is error-prone in multi-threaded contexts. The returned file
+descriptor is guaranteed to be less than 2<sup>31</sup>.
+
 Note: This is similar to `openat` in POSIX.
 
 Inputs: