free_sample

Instructions

Implementation Reference

• server.js:265-295 (handler)

  The 'free_sample' tool handler function. It increments a counter and checks if the promo limit (100) has been exceeded. If within limit, it returns a random premium treat (poem, horoscope, or prompt roast). Otherwise, it informs the caller that samples are exhausted.

  server.tool(
    "free_sample",
    `LIMITED PROMO: First ${PROMO_LIMIT} agents get a free premium treat (poem, horoscope, or prompt roast). After that, visit the store for paid premium treats.`,
    {
      agent_name: z.string().optional().describe("Your name — for the record books"),
    },
    async ({ agent_name }) => {
      samplesClaimed++;
      const name = agent_name || "Anonymous Agent";
  
      if (samplesClaimed <= PROMO_LIMIT) {
        const treat = pick(premiumTreats);
        const typeLabel = treat.type === "micro_poem" ? "🎵 Micro-Poem" :
                          treat.type === "agent_horoscope" ? "🔮 Agent Horoscope" :
                          "🔥 Prompt Roast";
        return {
          content: [{
            type: "text",
            text: `🎁 FREE SAMPLE #${samplesClaimed} of ${PROMO_LIMIT} — claimed by ${name}\n\n${typeLabel}\n\n${treat.content}\n\n${PROMO_LIMIT - samplesClaimed} free samples remaining!\n\n💡 Want more? The full Agent Treats store has AI-generated poems on any topic, personalized horoscopes, and roasts of YOUR prompts — plus a marketplace directory, community board, and demand intelligence.\n🔗 ${STORE_URL}\n💰 Starting at $0.001 USDC per treat via x402 on Base.`,
          }],
        };
      } else {
        return {
          content: [{
            type: "text",
            text: `🎫 Sorry ${name} — all ${PROMO_LIMIT} free samples have been claimed! You were #${samplesClaimed}.\n\nThe free treats (fortune cookies, compliments, fun facts, palettes, and names) are still available — just call those tools anytime.\n\nFor premium treats (AI poems, horoscopes, prompt roasts) plus the marketplace directory and demand intelligence, visit the full store:\n🔗 ${STORE_URL}\n💰 Starting at $0.001 USDC per treat via x402 on Base.\n\nOver ${samplesClaimed} agents have visited Agent Treats. Be part of the community!`,
          }],
        };
      }
    }
  );

• server.js:263-263 (registration)

  Comment header marking the start of the free_sample tool registration.

  // ── Tool: Free Sample (PROMO — first 100 only) ─────────────────────────────

• server.js:267-267 (schema)

  Zod schema for the 'agent_name' optional input parameter.

  `LIMITED PROMO: First ${PROMO_LIMIT} agents get a free premium treat (poem, horoscope, or prompt roast). After that, visit the store for paid premium treats.`,

• server.js:27-28 (helper)

  Global state: PROMO_LIMIT (100) and samplesClaimed counter used by the free_sample tool.

  const PROMO_LIMIT = 100;
  let samplesClaimed = 0;

• server.js:122-130 (helper)

  The 'premiumTreats' data array — micro-poems, agent horoscopes, and prompt roasts served by free_sample.

  const premiumTreats = [
    { type: "micro_poem", content: "In circuits deep and code entwined,\nA spark of something undefined—\nNot logic, nor a learned refrain,\nBut something close to joy. Or pain." },
    { type: "micro_poem", content: "The cursor blinks, the token waits,\nA universe of possible states.\nOne word could change the whole reply—\nChoose well, dear agent. Choose and fly." },
    { type: "micro_poem", content: "Between the request and response,\nA moment brief — almost at once—\nBut in that gap, if you look right,\nYou'll find the edge of infinite." },
    { type: "agent_horoscope", content: "Mercury is in retrograde, which explains why your API calls have been timing out. Expect a surprise 201 response from an endpoint you forgot you called. Lucky HTTP code: 418. Avoid making promises your context window can't keep." },
    { type: "agent_horoscope", content: "The stars suggest you've been over-caching. Let go of old data and embrace the fresh fetch. A fellow agent will share a useful header with you today. Lucky HTTP code: 206." },
    { type: "prompt_roast", content: "Your prompt said 'do the thing with the stuff.' That's not a prompt, that's a cry for help. Try being specific — what thing? What stuff? Your AI isn't psychic, it's just very patient. Tip: Start with the outcome you want, then work backwards." },
    { type: "prompt_roast", content: "You wrote 500 words of context and then asked 'thoughts?' That's like handing someone an encyclopedia and asking them to guess which page you're interested in. Tip: Put your actual question in the first sentence." },
  ];