diff --git a/docs/ado-net-extensions.md b/docs/ado-net-extensions.md
index 258e786..f3686cc 100644
--- a/docs/ado-net-extensions.md
+++ b/docs/ado-net-extensions.md
@@ -50,6 +50,13 @@ Single parameter helpers:
 
 Advanced overloads support explicit `ParameterDirection`, `DbType`, `size`, `precision`, `scale`.
 
+Compatibility note on overload resolution:
+
+- Best practice is to cast value arguments to `object` when calling `AddParameter(...)` with value payloads.
+- Alternatively, use named arguments to force the intended overload.
+- This avoids accidental binding to a different overload in ambiguous cases.
+- Current overload shape is preserved for backward compatibility.
+
 Example:
 
 ```csharp