diff --git a/website/docs/configuration/functions/coalesce.html.md b/website/docs/configuration/functions/coalesce.html.md
index 13c970f72..d4b409d3c 100644
--- a/website/docs/configuration/functions/coalesce.html.md
+++ b/website/docs/configuration/functions/coalesce.html.md
@@ -16,6 +16,11 @@ earlier, see
 `coalesce` takes any number of arguments and returns the first one
 that isn't null or an empty string.
 
+All of the arguments must be of the same type. Terraform will try to
+convert mismatched arguments to the most general of the types that all
+arguments can convert to, or return an error if the types are incompatible.
+The result type is the same as the type of all of the arguments.
+
 ## Examples
 
 ```
@@ -35,6 +40,22 @@ symbol to expand the list as arguments:
 b
 ```
 
+Terraform attempts to select a result type that all of the arguments can
+convert to, so mixing argument types may produce surprising results due to
+Terraform's automatic type conversion rules:
+
+```
+> coalesce(1, "hello")
+"1"
+> coalesce(true, "hello")
+"true"
+> coalesce({}, "hello")
+
+Error: Error in function call
+
+Call to function "coalesce" failed: all arguments must have the same type.
+```
+
 ## Related Functions
 
 * [`coalescelist`](./coalescelist.html) performs a similar operation with