diff --git a/README.md b/README.md
index a9e3c12..767bb6a 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,11 @@ data "cedar_policyset" "example" {
   policy {
     effect = "permit"
 
+    annotation {
+      name = "advice"
+      value = "Allow admins to read public resources unless owned by Alice"
+    }
+
     principal_in = {
       type = "Group"
       id   = "admins"
@@ -30,6 +35,7 @@ data "cedar_policyset" "example" {
 The `data.cedar_policyset.example.text` output will be:
 
 ```
+@advice("Allow admins to read public resources unless owned by Alice")
 permit (
     principal in Group::"admins",
     action == Action::"Read",
diff --git a/docs/index.md b/docs/index.md
index fe81f75..1f8963d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,6 +11,11 @@ data "cedar_policyset" "example" {
   policy {
     effect = "permit"
 
+    annotation {
+      name = "advice"
+      value = "Allow admins to read public resources unless owned by Alice"
+    }
+
     principal_in = {
       type = "Group"
       id   = "admins"
@@ -34,6 +39,7 @@ data "cedar_policyset" "example" {
 The `data.cedar_policyset.example.text` output will be:
 
 ```
+@advice("Allow admins to read public resources unless owned by Alice")
 permit (
     principal in Group::"admins",
     action == Action::"Read",
diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
index fe81f75..1f8963d 100644
--- a/templates/index.md.tmpl
+++ b/templates/index.md.tmpl
@@ -11,6 +11,11 @@ data "cedar_policyset" "example" {
   policy {
     effect = "permit"
 
+    annotation {
+      name = "advice"
+      value = "Allow admins to read public resources unless owned by Alice"
+    }
+
     principal_in = {
       type = "Group"
       id   = "admins"
@@ -34,6 +39,7 @@ data "cedar_policyset" "example" {
 The `data.cedar_policyset.example.text` output will be:
 
 ```
+@advice("Allow admins to read public resources unless owned by Alice")
 permit (
     principal in Group::"admins",
     action == Action::"Read",