`generate_rap_verse`

The flagship tool lives at dapp/app/lib/mcp/tools/agent-rap-verse/index.ts. It wraps the multi-phase orchestrator in orchestrator.ts, letting the MCP registry expose a single function the LLM can call during rap battle flows.

Handler Flow

Inputs — AgentParams accepts chatHistory, userContext (wallet, NFT palette), and an optional roundNumber.
Phases — runAgent walks through strategy planning, resource gathering (pinecone_search, meme/rhyme pulls, wallet checks), composition, self-review, and optional refinement.
Outputs — The handler streams both the verse text and a structured JSON payload with strategy metadata, list of resources used, and any generated image payloads (tagged as { kind: 'store-image' } for the frontend hydrator).


// dapp/app/lib/mcp/tools/agent-rap-verse/index.ts
const tool: Tool<AgentParams> = {
  name: 'generate_rap_verse',
  description: 'AI agent that ... composes original verses',
  inputSchema: InputSchema,
  async handler(params: AgentParams) {
    const output = await runAgent(params);
    const text = textResult(output.verse);
    const json = jsonResult({
      verse: output.verse,
      round: params.roundNumber || 1,
      strategy: output.metadata.strategy,
      resourcesUsed: output.metadata.resourcesUsed,
      refinementCount: output.metadata.refinementCount,
      review: output.metadata.reviewResults,
      generatedAt: output.metadata.generatedAt,
    });
    const imageJsonParts = output.imagePayloads.map(payload => ({
      type: 'json' as const,
      data: payload,
    }));
    return { content: [...text.content, ...json.content, ...imageJsonParts] };
  },
};

Presenter Signals

dapp/components/chatBot/ToolActivity/catalog/presenters/agent_rap_verse.presenter.ts keeps chips tied to the round structure:

Status	Label	Notes
pending	`Cooking Verse N/3`	Derives the round from `chip.input.roundNumber`.
success	`Verse N/3 Ready`	Reads the `round` field from the JSON payload; text is fixed to ”🔥 Bars dropped”.
error	`Verse N/3 Failed`	Falls back to “Agent choked on the mic” when no explicit error text is provided.

Playground Demo

Submit message to see the tool use process simulated.

Why it Matters

The tool is scoped to the agentBattle mode only—rap battles stick to inline prompting so they can enforce the one-balance-check rule. Because generate_rap_verse can emit generated images and meme references, it acts as the hub that calls other MCP tools internally whenever the agent mode is active.

Images travel with { kind: 'store-image' } payloads, enabling the inline <img src="store://..."> renderer documented on the Chat Experience page.
Quota Safety is maintained by the chat handler, but the agent itself still tracks its refinement count so you can tweak limits later without editing the orchestrator.