diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md
index 7cd9c0fb6..15a0895fc 100644
--- a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md
+++ b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/agent-conversation.md
@@ -17,7 +17,7 @@ List recent agent conversations
 
 **Flags:**
 - `-n, --limit <value> - Number of conversations (1-1000) - (default: "25")`
-- `-q, --query <value> - Search query`
+- `-q, --query <value> - Any matching span selects its conversation; totals include all spans in selected projects and time range`
 - `-t, --period <value> - Time range: "7d", "2024-01-01..2024-02-01", ">=2024-01-01" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
@@ -63,8 +63,17 @@ sentry agent-conversation list my-project
 # Show more, last 24 hours
 sentry agent-conversation list --limit 50 --period 24h
 
-# Filter conversations
-sentry agent-conversation list -q "has:errors"
+# Find conversations with errors
+sentry agent-conversation list -q "conversation.errors:>0"
+
+# Find conversations for an agent
+sentry agent-conversation list -q "gen_ai.agent.name:my-agent"
+
+# Find conversations with more than two tool calls
+sentry agent-conversation list -q "conversation.toolCalls:>2"
+
+# Find conversations that used a tool
+sentry agent-conversation list -q "gen_ai.tool.name:search_issues"
 
 # Paginate through project results
 sentry agent-conversation list my-org/my-project -c next
diff --git a/packages/cli/src/commands/agent-conversation/list.ts b/packages/cli/src/commands/agent-conversation/list.ts
index 42e32ca47..71c31c5f9 100644
--- a/packages/cli/src/commands/agent-conversation/list.ts
+++ b/packages/cli/src/commands/agent-conversation/list.ts
@@ -134,8 +134,23 @@ export const listCommand = buildListCommand("agent-conversation", {
         command: "sentry agent-conversation list --limit 50 --period 24h",
       },
       {
-        description: "Filter conversations",
-        command: 'sentry agent-conversation list -q "has:errors"',
+        description: "Find conversations with errors",
+        command: 'sentry agent-conversation list -q "conversation.errors:>0"',
+      },
+      {
+        description: "Find conversations for an agent",
+        command:
+          'sentry agent-conversation list -q "gen_ai.agent.name:my-agent"',
+      },
+      {
+        description: "Find conversations with more than two tool calls",
+        command:
+          'sentry agent-conversation list -q "conversation.toolCalls:>2"',
+      },
+      {
+        description: "Find conversations that used a tool",
+        command:
+          'sentry agent-conversation list -q "gen_ai.tool.name:search_issues"',
       },
       {
         description: "Paginate through project results",
@@ -160,7 +175,8 @@ export const listCommand = buildListCommand("agent-conversation", {
       query: {
         kind: "parsed",
         parse: String,
-        brief: "Search query",
+        brief:
+          "Any matching span selects its conversation; totals include all spans in selected projects and time range",
         optional: true,
       },
       period: LIST_PERIOD_FLAG,