docs: add AI hints for improved agent understanding

guides/ai-agents.mdx

@@ -115,9 +115,105 @@ Good documentation is crucial for AI to understand your data models and provide
 - **Write clear, descriptive names** for metrics and dimensions
 - **Add detailed descriptions** to all metrics and dimensions explaining what they represent
 - **Include example questions** in descriptions that AI could answer with the metric
+- **Use AI hints** to provide additional context specifically for AI agents
 
 Remember: If your colleague wouldn't understand your documentation, neither will the AI agent. The more context you provide, the better the AI can interpret and analyze your data.
 
+#### Using AI hints
+
+AI hints are specialized metadata fields that provide additional context specifically for AI agents. These hints help the AI better understand your data models, business logic, and how to interpret your metrics and dimensions.
+
+<Info>
+  AI hints are internal metadata used only by AI agents and are not displayed to
+  users in the Lightdash interface. When both AI hints and descriptions are
+  present, AI hints take precedence for AI agent prompts.
+</Info>
+
+You can add AI hints at three levels:
+
+**Model-level hints** - Provide context about the entire table:
+
+<CodeGroup>
+
+```yaml dbt 1.10+
+models:
+  - name: customers
+    config:
+      meta:
+        ai_hint: |
+          This is a customers table containing customer information and derived facts.
+          Use this for customer demographics, behavior analysis, and segmentation.
+```
+
+```yaml dbt <=1.9
+models:
+  - name: customers
+    meta:
+      ai_hint: |
+        This is a customers table containing customer information and derived facts.
+        Use this for customer demographics, behavior analysis, and segmentation.
+```
+
+</CodeGroup>
+
+**Dimension-level hints** - Explain individual columns:
+
+<CodeGroup>
+
+```yaml dbt 1.10+
+columns:
+  - name: last_name
+    config:
+      meta:
+        dimension:
+          ai_hint: |
+            Customer's last name. Contains PII data.
+            Use for customer identification but be mindful of privacy.
+```
+
+```yaml dbt <=1.9
+columns:
+  - name: last_name
+    meta:
+      dimension:
+        ai_hint: |
+          Customer's last name. Contains PII data.
+          Use for customer identification but be mindful of privacy.
+```
+
+</CodeGroup>
+
+**Metric-level hints** - Clarify what metrics measure:
+
+<CodeGroup>
+
+```yaml dbt 1.10+
+columns:
+  - name: customer_id
+    config:
+      meta:
+        metrics:
+          unique_customer_count:
+            type: count_distinct
+            ai_hint: |
+              Unique customer count for business reporting.
+              Use this for customer acquisition and retention analysis.
+```
+
+```yaml dbt <=1.9
+columns:
+  - name: customer_id
+    meta:
+      metrics:
+        unique_customer_count:
+          type: count_distinct
+          ai_hint: |
+            Unique customer count for business reporting.
+            Use this for customer acquisition and retention analysis.
+```
+
+</CodeGroup>
+
 ### Writing effective instructions
 
 Think of your instructions as teaching your AI agent about your world. The better you explain your business context and preferences, the more useful and relevant your agent's responses will be.