fix(conversations): format reported costs (#1303)

`search_agent_conversations` now returns presentation-ready USD text in
`totalCost`, matching Agent Monitoring display rules. This removes
floating-point artifacts such as `0.6260719999999997`: regular values
use compact currency formatting, positive sub-cent values render as
`<$0.01`, and zero renders as `—`.

This changes `totalCost` in the tool output schema from a number to a
string. Consumers should treat this field as a display value rather than
parse it for numeric operations.

Fixes TET-2953

Co-authored-by: GPT-5.6 Codex <noreply@openai.com>

Author: vgrozdanic

docs/specs/ai-conversations.md

@@ -220,7 +220,7 @@ Each result should include:
 - AI call count.
 - Tool call count and tool error count.
 - Tool names.
-- Total tokens and total cost.
+- Total tokens and a display-formatted USD total cost. Use `—` for zero, `<$0.01` for positive sub-cent costs, and compact currency formatting otherwise.
 - Trace count and a small sample of trace IDs.
 
 Search and detail structured outputs use Unix millisecond timestamps for

packages/mcp-core/src/skillDefinitions.json

@@ -169,7 +169,7 @@
       },
       {
         "name": "search_agent_conversations",
-        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
+        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), USD cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
         "requiredScopes": ["event:read", "project:read"]
       },
       {
@@ -249,7 +249,7 @@
       },
       {
         "name": "search_agent_conversations",
-        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
+        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), USD cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
         "requiredScopes": ["event:read", "project:read"]
       },
       {
@@ -380,7 +380,7 @@
       },
       {
         "name": "search_agent_conversations",
-        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
+        "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), USD cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
         "requiredScopes": ["event:read", "project:read"]
       },
       {

packages/mcp-core/src/toolDefinitions.json

@@ -4537,7 +4537,7 @@
   },
   {
     "name": "search_agent_conversations",
-    "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
+    "description": "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.\n\nUse this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.\nEach row includes title (when available), USD cost, tokens, call counts, previews, and other list metadata.\nUse get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.\n\n<examples>\nsearch_agent_conversations(organizationSlug='my-org', query='failed conversations', period='7d')\nsearch_agent_conversations(organizationSlug='my-org', query='checkout', project='backend')\n</examples>",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -4684,7 +4684,7 @@
                 "type": "number"
               },
               "totalCost": {
-                "type": "number"
+                "type": "string"
               },
               "traceCount": {
                 "type": "number"
@@ -4949,7 +4949,7 @@
                 "type": "number"
               },
               "totalCost": {
-                "type": "number"
+                "type": "string"
               },
               "traceCount": {
                 "type": "number"

packages/mcp-core/src/tools/catalog/search-agent-conversations.test.ts

@@ -16,7 +16,7 @@ const baseConversation = {
   llmCalls: 2,
   toolCalls: 1,
   totalTokens: 1200,
-  totalCost: 0.012,
+  totalCost: 0.6260719999999997,
   startTimestamp: 1713805400000,
   endTimestamp: 1713805415000,
   traceCount: 1,
@@ -113,7 +113,7 @@ describe("search_agent_conversations", () => {
             "toolNames": [
               "search_events",
             ],
-            "totalCost": 0.012,
+            "totalCost": "$0.626",
             "totalTokens": 1200,
             "traceCount": 1,
             "url": "https://test-org.sentry.io/explore/conversations/conv-123/",
@@ -139,6 +139,42 @@ describe("search_agent_conversations", () => {
     );
   });
 
+  it("uses the Agent Monitoring display rules for small and missing costs", async () => {
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/test-org/agents/conversations/",
+        () =>
+          HttpResponse.json([
+            {
+              ...baseConversation,
+              conversationId: "sub-cent",
+              totalCost: 0.00333,
+            },
+            { ...baseConversation, conversationId: "missing", totalCost: 0 },
+          ]),
+      ),
+    );
+
+    const result = await searchAIConversations.handler(
+      {
+        organizationSlug: "test-org",
+        period: "30d",
+        limit: 10,
+      },
+      getServerContext(),
+    );
+
+    const structuredContent = getStructuredContent<{
+      conversations: Array<{ totalCost: string }>;
+    }>(result);
+
+    expect(
+      structuredContent.conversations.map(
+        (conversation) => conversation.totalCost,
+      ),
+    ).toEqual(["<$0.01", "—"]);
+  });
+
   it("keeps search results concise for large conversations", async () => {
     mswServer.use(
       http.get(

packages/mcp-core/src/tools/catalog/search-agent-conversations.ts

@@ -19,6 +19,12 @@ import type { ServerContext } from "../../types";
 
 const PREVIEW_LENGTH = 240;
 const TRACE_ID_SAMPLE_SIZE = 3;
+const usdFormatter = new Intl.NumberFormat("en-US", {
+  style: "currency",
+  currency: "USD",
+  notation: "compact",
+  maximumSignificantDigits: 3,
+});
 
 const aiConversationSearchResultSchema = z.object({
   conversationId: z.string(),
@@ -32,7 +38,7 @@ const aiConversationSearchResultSchema = z.object({
   toolCallCount: z.number(),
   toolErrorCount: z.number(),
   totalTokens: z.number(),
-  totalCost: z.number(),
+  totalCost: z.string(),
   traceCount: z.number(),
   sampleTraceIds: z.array(z.string()),
   firstInputPreview: z.string().nullable(),
@@ -111,6 +117,16 @@ function previewText(value: string | null): string | null {
   return `${value.slice(0, PREVIEW_LENGTH - 3)}...`;
 }
 
+function formatLLMCost(cost: number): string {
+  if (cost === 0) {
+    return "—";
+  }
+  if (cost > 0 && cost < 0.01) {
+    return "<$0.01";
+  }
+  return usdFormatter.format(cost);
+}
+
 function projectUser(user: AIConversationSummary["user"]) {
   if (!user) {
     return null;
@@ -165,7 +181,7 @@ function buildArtifact(
         aiCallCount: llmCalls,
         toolCallCount: toolCalls,
         totalTokens,
-        totalCost,
+        totalCost: formatLLMCost(totalCost),
         startTimestamp,
         endTimestamp,
         traceCount,
@@ -190,7 +206,7 @@ export default defineTool({
     "Search Sentry Agent Conversations, formerly called AI Conversations, and return one summary row per conversation.",
     "",
     "Use this tool to find or list Agent Conversations. Results are conversation summaries, not raw span rows.",
-    "Each row includes title (when available), cost, tokens, call counts, previews, and other list metadata.",
+    "Each row includes title (when available), USD cost, tokens, call counts, previews, and other list metadata.",
     "Use get_agent_conversation_details with a conversationId to fetch the transcript. Use get_sentry_resource for Sentry conversation URLs.",
     "",
     "<examples>",