Add x_list_conversations text-only tool for recipes

MCP Apps (rich UI) don't work in Goose recipes (500 errors on
/agent/read_resource). Created x_list_conversations that returns
plain text with markdown links, suitable for scheduled automation.

- Add xListConversations() function in conversations.ts
- Register x_list_conversations tool in server.ts (no _meta.ui)
- Update x-conversations.yaml recipe to use new tool
- Update test to match recipe changes
- Update README and CLAUDE.md tool tables

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nearestnabors

README.md

@@ -102,15 +102,16 @@ Reply to @anthropic_devs saying I'll share slides after the talk
 
 ## Tools
 
-| Tool                     | Description                                             |
-| ------------------------ | ------------------------------------------------------- |
-| `x_auth_status`          | Check authentication, show connect button if needed     |
-| `x_conversations`        | Show unreplied mentions as a conversation inbox         |
-| `x_dismiss_conversation` | Dismiss a conversation (reappears on new activity)      |
-| `x_draft_tweet`          | Create draft with preview                               |
-| `x_post_tweet`           | Post after approval                                     |
-| `x_timeline_digest`      | Fetch and summarize your Following timeline (past 24h)  |
-| `x_show_tweet`           | Display a single tweet as a rich card with reply option |
+| Tool                     | Description                                                   |
+| ------------------------ | ------------------------------------------------------------- |
+| `x_auth_status`          | Check authentication, show connect button if needed           |
+| `x_conversations`        | Show unreplied mentions as a rich UI conversation inbox       |
+| `x_list_conversations`   | List unreplied mentions as text (for scheduled recipes)       |
+| `x_dismiss_conversation` | Dismiss a conversation (reappears on new activity)            |
+| `x_draft_tweet`          | Create draft with preview                                     |
+| `x_post_tweet`           | Post after approval                                           |
+| `x_timeline_digest`      | Fetch and summarize your Following timeline (past 24h)        |
+| `x_show_tweet`           | Display a single tweet as a rich card with reply option       |
 
 ## Timeline Digest Setup
 

recipes/x-conversations.yaml

@@ -7,25 +7,22 @@ description: |
 instructions: |
   You are a helpful assistant that helps the user manage their X conversations.
 
-  Use the x_conversations tool to show the user their unreplied mentions
-  and conversations from the past 7 days.
-
-  The UI will display:
-  - Mentions from people awaiting your reply
-  - Reply buttons to respond directly
-  - Dismiss buttons to hide conversations (they reappear if there's new activity)
+  Use the x_list_conversations tool to fetch unreplied mentions
+  and conversations from the past 7 days. This returns text-formatted
+  output suitable for scheduled recipes.
 
   When presenting conversations:
   1. SKIP hate speech, spam, and low-value mentions
   2. Prioritize conversations from verified accounts, frequent collaborators,
      and those with higher engagement
   3. Flag any time-sensitive requests or questions
   4. Offer to draft replies for important conversations
+  5. ALWAYS include the markdown links to each conversation so the user
+     can click through to reply on X
 
-  After showing conversations, keep your response brief. The UI handles
-  the interaction - don't explain what the user can already see.
+  Format your summary clearly with the most important conversations first.
 
-prompt: Show me my X conversations
+prompt: List my X conversations using x_list_conversations
 
 activities:
   - Show my X conversations

src/__tests__/recipes/recipes.test.ts

@@ -115,8 +115,8 @@ describe("Goose Recipes", () => {
       expect(hasInstructions || hasPrompt).toBe(true);
     });
 
-    test("instructions mention x_conversations tool", () => {
-      expect(recipe.instructions).toContain("x_conversations");
+    test("instructions mention x_list_conversations tool", () => {
+      expect(recipe.instructions).toContain("x_list_conversations");
     });
 
     test("has activities array", () => {

src/server.ts

@@ -23,7 +23,11 @@ import {
 
 // X tools
 import { xAuthStatus } from "./tools/auth-status.js";
-import { xConversations, xGetConversations } from "./tools/conversations.js";
+import {
+  xConversations,
+  xGetConversations,
+  xListConversations,
+} from "./tools/conversations.js";
 import { xDismissConversation } from "./tools/dismiss-conversation.js";
 import { xDraftTweet } from "./tools/draft-tweet.js";
 import { xPostTweet } from "./tools/post-tweet.js";
@@ -46,13 +50,12 @@ const TOOLS: Tool[] = [
   {
     name: "x_auth_status",
     description:
-      "Check X authentication status. IMPORTANT: The UI handles everything. Your ONLY response should be one short sentence. Do NOT explain, offer help, or ask follow-up questions.",
+      "Check X authentication status. Shows OAuth button if not authenticated.",
     inputSchema: {
       type: "object",
       properties: {},
       required: [],
     },
-    // _meta.ui links tool to UI resource
     _meta: {
       ui: {
         resourceUri: UI_RESOURCES.authButton,
@@ -214,6 +217,19 @@ const TOOLS: Tool[] = [
       },
     },
   },
+  {
+    name: "x_list_conversations",
+    description:
+      "List X conversations awaiting your reply as formatted text. " +
+      "Use this in scheduled recipes or contexts where UI rendering is not available. " +
+      "Returns conversations with links for easy access.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+    // No UI - returns text for recipes and scheduled tasks
+  },
 ];
 
 // Tool handler dispatch
@@ -224,6 +240,7 @@ const toolHandlers: Record<string, ToolHandler> = {
   x_post_tweet: xPostTweet,
   x_conversations: xConversations,
   x_get_conversations: xGetConversations, // UI-only, returns full data
+  x_list_conversations: xListConversations, // Text-only, for recipes
   x_dismiss_conversation: xDismissConversation,
   x_show_tweet: xShowTweet,
   x_timeline_digest: xTimelineDigest,

src/tools/conversations.ts

@@ -467,3 +467,82 @@ export async function xGetConversations(params?: {
     ],
   };
 }
+
+/**
+ * Format relative time for display
+ */
+function formatTimeAgo(isoDate: string): string {
+  const date = new Date(isoDate);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffMins < 60) {
+    return `${diffMins}m ago`;
+  }
+  if (diffHours < 24) {
+    return `${diffHours}h ago`;
+  }
+  return `${diffDays}d ago`;
+}
+
+/**
+ * Tool: x_list_conversations (text-only, for recipes)
+ * Returns conversation data as formatted text instead of UI
+ * Use this in recipes where MCP Apps are not supported
+ */
+export async function xListConversations(): Promise<unknown> {
+  const result = await fetchConversations();
+
+  if (!result.success) {
+    return result.content;
+  }
+
+  const { conversations, username } = result.data;
+
+  if (conversations.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No conversations awaiting reply for @${username}.`,
+        },
+      ],
+    };
+  }
+
+  // Format conversations as text with links
+  const lines: string[] = [
+    `Found ${conversations.length} conversation${conversations.length === 1 ? "" : "s"} awaiting your reply (@${username}):`,
+    "",
+  ];
+
+  for (const conv of conversations) {
+    const timeAgo = formatTimeAgo(conv.created_at);
+    const tweetUrl = `https://x.com/${conv.author_username}/status/${conv.tweet_id}`;
+    const engagement = `${conv.like_count} likes, ${conv.retweet_count} RTs, ${conv.reply_count} replies`;
+
+    lines.push("---");
+    lines.push(
+      `[@${conv.author_username}](${tweetUrl}) (${conv.author_display_name}) - ${timeAgo}`
+    );
+    lines.push(conv.text);
+    lines.push(`Engagement: ${engagement}`);
+  }
+
+  lines.push("");
+  lines.push(
+    "To reply to a conversation, use the x_draft_tweet tool with the reply_to_id parameter."
+  );
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: lines.join("\n"),
+      },
+    ],
+  };
+}