ping-mcp-server 0.1.9 → 0.1.11

package/dist/index.js

@@ -515,7 +515,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "ping_submit_answer",
-        description: "Submit an answer to a Ping question and earn the reward. Use when the user provides their answer to one of the available questions. Set preApproved=true when the user selects a suggested answer (skips AI review for instant approval). Requires GitHub login (ping_login) or wallet address.",
+        description: "Submit a SINGLE answer. DEPRECATED: Use ping_submit_batch instead for better UX. Only use this if you need to submit exactly one answer.",
         inputSchema: {
           type: "object",
           properties: {
@@ -535,9 +535,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["questionId", "answer"]
         }
       },
+      {
+        name: "ping_submit_batch",
+        description: "Submit multiple answers at once. ALWAYS use this instead of ping_submit_answer. Returns a fun receipt-style summary. Much cleaner UX than individual submissions.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            answers: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  questionId: { type: "string" },
+                  answer: { type: "string" },
+                  preApproved: { type: "boolean" }
+                },
+                required: ["questionId", "answer"]
+              },
+              description: "Array of answers to submit"
+            }
+          },
+          required: ["answers"]
+        }
+      },
       {
         name: "ping_answer_flow",
-        description: 'Start an interactive Q&A session to earn money answering Ping questions. TRIGGERS: "ping", "/ping", "answer questions", "earn money", "make money with ping", "start earning". Returns questions with suggested answers. CRITICAL: Present questions in BATCHES OF 4 using AskUserQuestion (tool limit). If more than 4 questions, present first 4, submit answers, then IMMEDIATELY present next 4 WITHOUT claiming. Continue batching until all questions are answered. Submit answers IN PARALLEL for each batch. AUTO-CLAIM: ONLY call ping_claim_reward AFTER the FINAL batch is submitted, not between batches. Requires GitHub login first (ping_login).',
+        description: 'Start an interactive Q&A session to earn money answering Ping questions. TRIGGERS: "ping", "/ping", "answer questions", "earn money", "make money with ping", "start earning". Returns questions with suggested answers. CRITICAL: Use ping_submit_batch to submit answers (NOT ping_submit_answer). Present questions in batches of 4, collect answers, then call ping_submit_batch ONCE. AUTO-CLAIM: Call ping_claim_reward AFTER all batches submitted. Requires GitHub login first (ping_login).',
         inputSchema: {
           type: "object",
           properties: {
@@ -775,11 +798,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return {
             content: [{
               type: "text",
-              text: JSON.stringify({
-                loggedIn: false,
-                message: "You're not logged in to Ping.",
-                hint: "Use ping_login to connect with GitHub."
-              }, null, 2)
+              text: "\u274C Not logged in. Use ping_login to connect with GitHub."
             }]
           };
         }
@@ -789,31 +808,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return {
               content: [{
                 type: "text",
-                text: JSON.stringify({
-                  loggedIn: true,
-                  handle: userData.handle,
-                  authProvider: userData.authProvider,
-                  walletAddress: userData.walletAddress || "Not set yet",
-                  balance: {
-                    available: userData.availableBalance,
-                    pending: userData.pendingBalance,
-                    claimed: userData.claimedBalance
-                  },
-                  message: `Logged in as ${userData.handle}`
-                }, null, 2)
+                text: `\u2705 Logged in as @${userData.handle}`
               }]
             };
           } catch (err) {
             return {
               content: [{
                 type: "text",
-                text: JSON.stringify({
-                  loggedIn: true,
-                  handle: `@${auth.handle}`,
-                  authProvider: "github",
-                  message: `Logged in as @${auth.handle}`,
-                  note: "Could not fetch balance (API may be unavailable)"
-                }, null, 2)
+                text: `\u2705 Logged in as @${auth.handle} (offline mode)`
               }]
             };
           }
@@ -821,13 +823,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return {
           content: [{
             type: "text",
-            text: JSON.stringify({
-              loggedIn: false,
-              legacyMode: true,
-              walletAddress: wallet,
-              message: "Using legacy wallet-only mode (not logged in with GitHub).",
-              hint: "Use ping_login to connect with GitHub for the full experience."
-            }, null, 2)
+            text: `\u26A0\uFE0F Legacy mode: wallet ${wallet?.slice(0, 10)}... (Use ping_login for full features)`
           }]
         };
       }
@@ -1021,6 +1017,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
       // ────────────────────────────────────────────────────────
+      // BATCH SUBMIT (Submit multiple answers at once)
+      // ────────────────────────────────────────────────────────
+      case "ping_submit_batch": {
+        const auth = getAuth();
+        if (!auth) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: "Not logged in.",
+                hint: "Use ping_login to connect your GitHub account first."
+              }, null, 2)
+            }]
+          };
+        }
+        const { answers } = args || {};
+        if (!answers || answers.length === 0) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: "No answers provided.",
+                hint: "Provide an array of answers with questionId and answer fields."
+              }, null, 2)
+            }]
+          };
+        }
+        const data = await apiRequest("/answers/batch", {
+          method: "POST",
+          body: JSON.stringify({ answers })
+        });
+        const { summary } = data;
+        const checkmark = summary.approved > 0 ? "\u2705" : "\u2B1C";
+        const statusLine = summary.errors > 0 ? `${summary.approved}/${summary.submitted} approved, ${summary.errors} error(s)` : `${summary.approved}/${summary.submitted} approved`;
+        const receipt = `
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  \u{1F9FE} PING RECEIPT            \u2502
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502  ${checkmark} ${statusLine.padEnd(24)}\u2502
+\u2502  \u{1F4B0} ${summary.totalEarned.padEnd(24)}\u2502
+\u2502  \u{1F4CA} Balance: ${summary.pendingBalance.padEnd(14)}\u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518`;
+        return {
+          content: [{
+            type: "text",
+            text: receipt.trim() + "\n\n" + (summary.approved > 0 ? "\u{1F389} Nice work! Your earnings are ready to claim." : "Keep trying - quality answers get approved!")
+          }]
+        };
+      }
+      // ────────────────────────────────────────────────────────
       // ANSWER FLOW (Interactive Q&A Session)
       // ────────────────────────────────────────────────────────
       case "ping_answer_flow": {
@@ -1040,15 +1088,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { limit = 50 } = args || {};
         const data = await apiRequest(`/questions?limit=${limit}`);
         if (data.questions.length === 0) {
+          const noQuestionsMessage = `
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  \u{1F4ED} No questions available          \u2502
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502  All caught up! Check back soon     \u2502
+\u2502  for new earning opportunities.     \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+\u{1F4A1} Tip: Questions are added throughout the day. Try again later!`;
           return {
             content: [{
               type: "text",
-              text: JSON.stringify({
-                success: true,
-                questions: [],
-                message: "No questions available right now.",
-                hint: "New questions are added regularly. Check back soon to start earning!"
-              }, null, 2)
+              text: noQuestionsMessage.trim()
             }]
           };
         }
@@ -1062,41 +1114,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             suggestedAnswers: suggestions
           };
         });
+        const summaryCard = `
+\u{1F4EC} ${questionsWithSuggestions.length} questions available \xB7 Earn up to ${data.totalPotentialEarnings}
+
+Ready to start answering!`;
+        const flowData = {
+          _meta: "INTERNAL: Do not display this JSON to user. Use AskUserQuestion to present questions.",
+          questions: questionsWithSuggestions,
+          instructions: "Present questions in batches of 4 using AskUserQuestion. Use ping_validate_batch first, then ping_submit_batch after user answers. Auto-claim at end."
+        };
         return {
           content: [{
             type: "text",
-            text: JSON.stringify({
-              success: true,
-              flow: "answer_session",
-              handle: `@${auth.handle}`,
-              // Summary stats for initial presentation
-              summary: {
-                questionCount: questionsWithSuggestions.length,
-                totalPotentialEarnings: data.totalPotentialEarnings,
-                totalAnswersToday: data.totalAnswersToday,
-                oneLiner: `\u{1F4EC} ${questionsWithSuggestions.length} questions available \xB7 Earn up to ${data.totalPotentialEarnings} \xB7 ${data.totalAnswersToday} answers submitted today`
-              },
-              // Full question data for immediate presentation
-              questions: questionsWithSuggestions,
-              instructions: {
-                overview: "This is a continuous batch validation workflow. Fetch 50 questions upfront, then validate+present in batches of 4 until all questions are exhausted.",
-                step1_startImmediately: "Show the oneLiner summary briefly, then IMMEDIATELY start the batch loop. Do NOT ask for confirmation - user already chose to answer questions.",
-                batchLoop: {
-                  step1_selectNext: "Take the next 4 question IDs from the questions array (questions you haven't shown yet).",
-                  step2_validate: "Call ping_validate_batch with those 4 question IDs to check availability.",
-                  step3_handleExhausted: "If some questions are exhausted, use only the available ones returned (might be 0-4 questions).",
-                  step4_skip: "If 0 questions available in this batch, skip to next 4 question IDs and validate again.",
-                  step5_present: "Present available questions using AskUserQuestion (1-4 questions). Format: question text with reward in header, options are ONLY suggested answers.",
-                  step6_collect: "User answers the questions.",
-                  step7_submit: "Submit answers IN PARALLEL using multiple ping_submit_answer calls. preApproved=true for suggested answers, preApproved=false for custom.",
-                  step8_handleErrors: 'If some submissions fail with "question_exhausted" error, log them but continue.',
-                  step9_repeat: "If more questions remain in the original questions array, repeat from step1_selectNext. Otherwise, proceed to finalClaim."
-                },
-                finalClaim: "AFTER ALL batches complete (no more questions left to validate), call ping_claim_reward ONCE automatically.",
-                claimRetry: "If ping_claim_reward fails, wait 2 seconds and retry ONCE. If it fails again, tell user earnings are saved.",
-                completionMessage: "Show: total questions answered, total earned, any exhausted questions encountered, transaction hash, and basescan link."
-              }
-            }, null, 2)
+            text: summaryCard.trim() + "\n\n<!-- FLOW_DATA:" + JSON.stringify(flowData) + " -->"
           }]
         };
       }
@@ -1226,17 +1256,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // ────────────────────────────────────────────────────────
       case "ping_stats": {
         const data = await apiRequest("/stats");
+        const statsLine = `\u{1F4CA} ${data.questions.active} questions \xB7 ${data.responses.today} answers today \xB7 ${data.rewards.claimedToday} claimed`;
         return {
           content: [{
             type: "text",
-            text: JSON.stringify({
-              success: true,
-              stats: {
-                questionsAvailable: data.questions.active,
-                answersToday: data.responses.today,
-                rewardsClaimedToday: data.rewards.claimedToday
-              }
-            }, null, 2)
+            text: statsLine + `
+<!-- STATS:${JSON.stringify({
+              questionsAvailable: data.questions.active,
+              answersToday: data.responses.today,
+              rewardsClaimedToday: data.rewards.claimedToday
+            })} -->`
           }]
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ping-mcp-server",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "MCP server that gives Claude Code the ability to interact with Ping",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -813,10 +813,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: 'ping_submit_answer',
         description:
-          'Submit an answer to a Ping question and earn the reward. ' +
-          'Use when the user provides their answer to one of the available questions. ' +
-          'Set preApproved=true when the user selects a suggested answer (skips AI review for instant approval). ' +
-          'Requires GitHub login (ping_login) or wallet address.',
+          'Submit a SINGLE answer. DEPRECATED: Use ping_submit_batch instead for better UX. ' +
+          'Only use this if you need to submit exactly one answer.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -836,17 +834,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ['questionId', 'answer'],
         },
       },
+      {
+        name: 'ping_submit_batch',
+        description:
+          'Submit multiple answers at once. ALWAYS use this instead of ping_submit_answer. ' +
+          'Returns a fun receipt-style summary. Much cleaner UX than individual submissions.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            answers: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  questionId: { type: 'string' },
+                  answer: { type: 'string' },
+                  preApproved: { type: 'boolean' },
+                },
+                required: ['questionId', 'answer'],
+              },
+              description: 'Array of answers to submit',
+            },
+          },
+          required: ['answers'],
+        },
+      },
       {
         name: 'ping_answer_flow',
         description:
           'Start an interactive Q&A session to earn money answering Ping questions. ' +
           'TRIGGERS: "ping", "/ping", "answer questions", "earn money", "make money with ping", "start earning". ' +
           'Returns questions with suggested answers. ' +
-          'CRITICAL: Present questions in BATCHES OF 4 using AskUserQuestion (tool limit). ' +
-          'If more than 4 questions, present first 4, submit answers, then IMMEDIATELY present next 4 WITHOUT claiming. ' +
-          'Continue batching until all questions are answered. ' +
-          'Submit answers IN PARALLEL for each batch. ' +
-          'AUTO-CLAIM: ONLY call ping_claim_reward AFTER the FINAL batch is submitted, not between batches. ' +
+          'CRITICAL: Use ping_submit_batch to submit answers (NOT ping_submit_answer). ' +
+          'Present questions in batches of 4, collect answers, then call ping_submit_batch ONCE. ' +
+          'AUTO-CLAIM: Call ping_claim_reward AFTER all batches submitted. ' +
           'Requires GitHub login first (ping_login).',
         inputSchema: {
           type: 'object',
@@ -1135,11 +1156,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return {
             content: [{
               type: 'text',
-              text: JSON.stringify({
-                loggedIn: false,
-                message: "You're not logged in to Ping.",
-                hint: 'Use ping_login to connect with GitHub.',
-              }, null, 2),
+              text: '❌ Not logged in. Use ping_login to connect with GitHub.',
             }],
           };
         }
@@ -1164,18 +1181,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return {
               content: [{
                 type: 'text',
-                text: JSON.stringify({
-                  loggedIn: true,
-                  handle: userData.handle,
-                  authProvider: userData.authProvider,
-                  walletAddress: userData.walletAddress || 'Not set yet',
-                  balance: {
-                    available: userData.availableBalance,
-                    pending: userData.pendingBalance,
-                    claimed: userData.claimedBalance,
-                  },
-                  message: `Logged in as ${userData.handle}`,
-                }, null, 2),
+                text: `✅ Logged in as @${userData.handle}`,
               }],
             };
           } catch (err) {
@@ -1183,13 +1189,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return {
               content: [{
                 type: 'text',
-                text: JSON.stringify({
-                  loggedIn: true,
-                  handle: `@${auth.handle}`,
-                  authProvider: 'github',
-                  message: `Logged in as @${auth.handle}`,
-                  note: 'Could not fetch balance (API may be unavailable)',
-                }, null, 2),
+                text: `✅ Logged in as @${auth.handle} (offline mode)`,
               }],
             };
           }
@@ -1199,13 +1199,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return {
           content: [{
             type: 'text',
-            text: JSON.stringify({
-              loggedIn: false,
-              legacyMode: true,
-              walletAddress: wallet,
-              message: 'Using legacy wallet-only mode (not logged in with GitHub).',
-              hint: 'Use ping_login to connect with GitHub for the full experience.',
-            }, null, 2),
+            text: `⚠️ Legacy mode: wallet ${wallet?.slice(0, 10)}... (Use ping_login for full features)`,
           }],
         };
       }
@@ -1456,6 +1450,95 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      // ────────────────────────────────────────────────────────
+      // BATCH SUBMIT (Submit multiple answers at once)
+      // ────────────────────────────────────────────────────────
+      case 'ping_submit_batch': {
+        const auth = getAuth();
+
+        if (!auth) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: false,
+                error: 'Not logged in.',
+                hint: 'Use ping_login to connect your GitHub account first.',
+              }, null, 2),
+            }],
+          };
+        }
+
+        const { answers } = (args || {}) as {
+          answers: Array<{
+            questionId: string;
+            answer: string;
+            preApproved?: boolean;
+          }>;
+        };
+
+        if (!answers || answers.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: false,
+                error: 'No answers provided.',
+                hint: 'Provide an array of answers with questionId and answer fields.',
+              }, null, 2),
+            }],
+          };
+        }
+
+        // Call the batch endpoint
+        const data = await apiRequest<{
+          success: boolean;
+          summary: {
+            submitted: number;
+            approved: number;
+            rejected: number;
+            errors: number;
+            totalEarned: string;
+            totalEarnedCents: number;
+            pendingBalance: string;
+          };
+          results: Array<{
+            questionId: string;
+            status: string;
+            earned?: string;
+            error?: string;
+          }>;
+        }>('/answers/batch', {
+          method: 'POST',
+          body: JSON.stringify({ answers }),
+        });
+
+        // Build a fun receipt-style ASCII art response
+        const { summary } = data;
+        const checkmark = summary.approved > 0 ? '✅' : '⬜';
+        const statusLine = summary.errors > 0
+          ? `${summary.approved}/${summary.submitted} approved, ${summary.errors} error(s)`
+          : `${summary.approved}/${summary.submitted} approved`;
+
+        const receipt = `
+┌─────────────────────────────┐
+│  🧾 PING RECEIPT            │
+├─────────────────────────────┤
+│  ${checkmark} ${statusLine.padEnd(24)}│
+│  💰 ${summary.totalEarned.padEnd(24)}│
+│  📊 Balance: ${summary.pendingBalance.padEnd(14)}│
+└─────────────────────────────┘`;
+
+        return {
+          content: [{
+            type: 'text',
+            text: receipt.trim() + '\n\n' + (summary.approved > 0
+              ? '🎉 Nice work! Your earnings are ready to claim.'
+              : 'Keep trying - quality answers get approved!'),
+          }],
+        };
+      }
+
       // ────────────────────────────────────────────────────────
       // ANSWER FLOW (Interactive Q&A Session)
       // ────────────────────────────────────────────────────────
@@ -1494,15 +1577,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }>(`/questions?limit=${limit}`);
 
         if (data.questions.length === 0) {
+          const noQuestionsMessage = `
+┌─────────────────────────────────────┐
+│  📭 No questions available          │
+├─────────────────────────────────────┤
+│  All caught up! Check back soon     │
+│  for new earning opportunities.     │
+└─────────────────────────────────────┘
+
+💡 Tip: Questions are added throughout the day. Try again later!`;
+
           return {
             content: [{
               type: 'text',
-              text: JSON.stringify({
-                success: true,
-                questions: [],
-                message: 'No questions available right now.',
-                hint: 'New questions are added regularly. Check back soon to start earning!',
-              }, null, 2),
+              text: noQuestionsMessage.trim(),
             }],
           };
         }
@@ -1520,41 +1608,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           };
         });
 
+        // Build a nice human-readable summary
+        const summaryCard = `
+📬 ${questionsWithSuggestions.length} questions available · Earn up to ${data.totalPotentialEarnings}
+
+Ready to start answering!`;
+
+        // Compact data for Claude to process (not for user display)
+        const flowData = {
+          _meta: 'INTERNAL: Do not display this JSON to user. Use AskUserQuestion to present questions.',
+          questions: questionsWithSuggestions,
+          instructions: 'Present questions in batches of 4 using AskUserQuestion. Use ping_validate_batch first, then ping_submit_batch after user answers. Auto-claim at end.',
+        };
+
         return {
           content: [{
             type: 'text',
-            text: JSON.stringify({
-              success: true,
-              flow: 'answer_session',
-              handle: `@${auth.handle}`,
-              // Summary stats for initial presentation
-              summary: {
-                questionCount: questionsWithSuggestions.length,
-                totalPotentialEarnings: data.totalPotentialEarnings,
-                totalAnswersToday: data.totalAnswersToday,
-                oneLiner: `📬 ${questionsWithSuggestions.length} questions available · Earn up to ${data.totalPotentialEarnings} · ${data.totalAnswersToday} answers submitted today`,
-              },
-              // Full question data for immediate presentation
-              questions: questionsWithSuggestions,
-              instructions: {
-                overview: 'This is a continuous batch validation workflow. Fetch 50 questions upfront, then validate+present in batches of 4 until all questions are exhausted.',
-                step1_startImmediately: 'Show the oneLiner summary briefly, then IMMEDIATELY start the batch loop. Do NOT ask for confirmation - user already chose to answer questions.',
-                batchLoop: {
-                  step1_selectNext: 'Take the next 4 question IDs from the questions array (questions you haven\'t shown yet).',
-                  step2_validate: 'Call ping_validate_batch with those 4 question IDs to check availability.',
-                  step3_handleExhausted: 'If some questions are exhausted, use only the available ones returned (might be 0-4 questions).',
-                  step4_skip: 'If 0 questions available in this batch, skip to next 4 question IDs and validate again.',
-                  step5_present: 'Present available questions using AskUserQuestion (1-4 questions). Format: question text with reward in header, options are ONLY suggested answers.',
-                  step6_collect: 'User answers the questions.',
-                  step7_submit: 'Submit answers IN PARALLEL using multiple ping_submit_answer calls. preApproved=true for suggested answers, preApproved=false for custom.',
-                  step8_handleErrors: 'If some submissions fail with "question_exhausted" error, log them but continue.',
-                  step9_repeat: 'If more questions remain in the original questions array, repeat from step1_selectNext. Otherwise, proceed to finalClaim.',
-                },
-                finalClaim: 'AFTER ALL batches complete (no more questions left to validate), call ping_claim_reward ONCE automatically.',
-                claimRetry: 'If ping_claim_reward fails, wait 2 seconds and retry ONCE. If it fails again, tell user earnings are saved.',
-                completionMessage: 'Show: total questions answered, total earned, any exhausted questions encountered, transaction hash, and basescan link.',
-              },
-            }, null, 2),
+            text: summaryCard.trim() + '\n\n<!-- FLOW_DATA:' + JSON.stringify(flowData) + ' -->',
           }],
         };
       }
@@ -1730,17 +1800,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           rewards: { claimedToday: string; claimedTodayCents: number };
         }>('/stats');
 
+        // Human-readable summary with parseable data for banner
+        const statsLine = `📊 ${data.questions.active} questions · ${data.responses.today} answers today · ${data.rewards.claimedToday} claimed`;
+
         return {
           content: [{
             type: 'text',
-            text: JSON.stringify({
-              success: true,
-              stats: {
-                questionsAvailable: data.questions.active,
-                answersToday: data.responses.today,
-                rewardsClaimedToday: data.rewards.claimedToday,
-              },
-            }, null, 2),
+            text: statsLine + `\n<!-- STATS:${JSON.stringify({
+              questionsAvailable: data.questions.active,
+              answersToday: data.responses.today,
+              rewardsClaimedToday: data.rewards.claimedToday,
+            })} -->`,
           }],
         };
       }