diff --git a/packages/babel-helper-evaluate-path/README.md b/packages/babel-helper-evaluate-path/README.md
index 50eebc4bd..dcdbf98c6 100644
--- a/packages/babel-helper-evaluate-path/README.md
+++ b/packages/babel-helper-evaluate-path/README.md
@@ -1,6 +1,32 @@
 # # babel-helper-evaluate-path
 
-`path.evaluate` wrapped in a try catch
+A wrapper for babel's `path.evaluate`
+
+Fixes / Features:
+
++ Detect usages before initialization / declaration
+
+```js
+function foo() {
+  console.log(b); // ReferenceError
+  let b = 1;
+}
+
+function bar() {
+  console.log(a); // a is void 0
+  var a = 5;
+  console.log(a); // 5
+}
+```
+
++ Detect usages in scopes outside of initialization for vars (hoisted)
+
+```js
+function foo() {
+  if (a) var x = 5;
+  console.log(x); // cannot determine
+}
+```
 
 ## Installation