docs: document period-over-period comparisons in AI agents

guides/ai-agents/using-ai-agents.mdx

@@ -51,6 +51,30 @@ If your agent has data access disabled, pinning still works — the agent sees t
 
 ## Example use cases
 
+### Period-over-period comparisons
+
+AI agents can build period-over-period (PoP) queries directly from a natural language prompt. Ask for "revenue vs last month", "year-over-year users", or "compare this quarter to the previous one", and the agent adds a shifted comparison column next to the base metric — no need to open the [period comparison modal](/guides/period-over-period) yourself.
+
+**What you can ask:**
+
+- *"Show revenue by month, with previous-month comparison."*
+- *"Year-over-year users by quarter."*
+- *"Compare orders this week to the same week last year."*
+- *"MoM and YoY revenue in one chart."*
+
+The agent generates a query that includes a time dimension, the base metric, and one comparison column per request (for example, `Revenue` plus `Revenue (Previous month)`). Multiple comparisons on the same metric — such as month-over-month *and* year-over-year — appear as separate columns.
+
+**Requirements the agent enforces:**
+
+- The query must include a time-interval dimension (such as `orders_created_at_month`) — the agent adds one if your prompt doesn't.
+- The comparison granularity must match the dimension's time interval (`DAY`, `WEEK`, `MONTH`, `QUARTER`, or `YEAR`). `HOUR` and raw timestamps aren't supported.
+- The period offset must be at least `1`. Use `1` for the previous period, `12` with `MONTH` granularity for the same month last year, `4` with `QUARTER` for the same quarter last year, and so on.
+
+**Not a fit for PoP comparisons:**
+
+- **Month-to-date and year-to-date totals.** These are filtered aggregations, not period shifts. Ask the agent for a custom metric with a date filter instead.
+- **Growth rate or percent change columns.** The PoP column is generated by the agent, so it can't yet be referenced from a table calculation in the same query. Pull the comparison first, then add the percent-change calculation in the explorer.
+
 ### Advanced visualizations with window functions
 
 AI agents can handle complex analytical queries that would traditionally require writing intricate SQL or YAML configurations. In this example, we demonstrate building a 3-month rolling average visualization using nothing but natural language.