Find ranked social posts where people are describing the problem the user's SaaS solves, across Reddit, X, YouTube, and TikTok. Behavior: dispatches the full server-side pipeline (theme expansion, parallel platform search, AI scoring), persists a run row, blocks until the run completes (typically 60 to 120 seconds), and returns the scored leads. Consumes one credit on the user's plan. Idempotent only via the resulting run_id (use runs.get to re-read without spending another credit). Usage: call this when the user wants the full lead hunt for an idea. Do NOT call it twice for the same idea in the same session, use runs.get to re-analyse. Pair with idea.refine first if the idea is one or two words. After it returns, hand the run_id to outreach.plan for a Week-1 outreach plan and to outreach.draft for per-lead messages. Returns: scored leads (source, channel, title, url, lead_score 0-1, matched_signals including category and outreach hints), plus a header line with totals per source.

Run one round of conversational refinement on a SaaS idea before searching for leads. Behavior: hits the same /refine endpoint the usegorilla.app site uses. Stateless on the server side; the MCP caller must carry history across turns. Does not write any DB rows and does NOT consume a credit. Idempotent. Usage: call this on the first turn with just {idea}, ask the returned question to the user, then call again with the same idea, the previous refined_idea as current_refined_idea, and the new {question, answer} appended to history. Stop when status is 'ready' (readiness_score crosses ~75) or after max_turns. Do NOT call idea.refine after leads.find has already run, the refinement is a pre-search step. Returns: status (ready or needs_answer), refined_idea (full text), readiness_score (0-100) with reason, missing_info list, audience_model, and one next question with suggested options (or null if ready).

Run an ad-hoc search against ONE social platform (Reddit, X, YouTube, or TikTok) with caller-provided queries. Behavior: hits the platform-specific search edge function directly, bypassing theme-expansion and AI scoring. Consumes one credit per call. If a run_id is passed, results are written to that run for inspection later via runs.get. Without run_id, results are returned but not persisted. Usage: call this when leads.find under-fetched on a specific platform, or to test custom query phrasings (the queries you pass in ARE the queries that get run, no expansion). Do NOT use this as a substitute for leads.find when you want full pipeline behaviour: results from leads.search are unscored. To search all four platforms with AI scoring, call leads.find instead. Returns: leads array (raw posts with platform fields, no lead_score) and a count.

Generate the keyword scaffolding (core keywords, adjacent niches, pain points, competitor names, exclusion terms) for a product idea, without running searches. Behavior: hits the same theme-expansion endpoint leads.find calls internally as its first step. Consumes one credit. Stateless; nothing persists. Usage: call this when the user wants to see the search scaffolding before committing to a full run, or when planning manual outreach copy and you want the buyer-language vocabulary. Do NOT use this as a precursor to leads.find in the same session, leads.find runs theme expansion itself; calling both is double-billing. Returns: { core_keywords, adjacent_niches, pain_points, competitor_names, exclusion_terms } as string arrays.

Fetch the full result for a previously-started run by its run_id. Behavior: read-only DB query; no external calls and no credit consumed. Idempotent and safe to poll. If status is still 'running', returns whichever leads have already arrived (search-* functions stream into the same posts row as they finish). Usage: call this to re-analyse an earlier run without spending another credit, to hand a fresh leads payload to outreach.plan or outreach.draft, or to poll a long-running leads.find job. Do NOT call this without an existing run_id; use runs.list first if you need to find one. Returns: run_id, status (running / completed / failed / partial), idea text, results array (posts with source, channel, title, url, lead_score, matched_signals), and metadata { total_posts, elapsed_ms, errors[] }.

List the user's recent lead-generation runs, newest first, capped at 50. Behavior: read-only DB query scoped to the authenticated user. No external calls, no credit consumed. Idempotent. Usage: call this when the user wants to revisit a previous lead hunt, when you need a run_id to feed into runs.get / outreach.plan without re-running, or to confirm whether a recent leads.find has completed. Do NOT use this to enumerate other users' runs (the endpoint is user-scoped). Returns: { runs: [{ id, idea, status (completed/running/failed/partial), created_at (UNIX seconds), total_posts, product_title }] }, ordered by created_at desc.

Check the authenticated user's current plan, remaining weekly runs, referral credits, and whether any API keys are active. Behavior: read-only; hits the billing-status edge function which derives the live state from the billing + beta_access tables. Free, no credit consumed. Idempotent. Usage: call this BEFORE leads.find or leads.search if you want to confirm the user has runs available, or after a billing-error response to surface why the call was blocked. Useful for the agent to decide whether to recommend an upgrade. Do NOT poll this on a schedule, the values only change when Stripe webhooks fire (sub-minute polling adds no signal). Returns: { plan ('free'/'weekly'/'monthly'/'yearly'/'lifetime'), runs_this_week, weekly_limit, referral_credits, has_api_keys, plus billing_enabled and trial_expires_at when applicable }.

Generate a platform-tuned outreach message for a specific lead the user wants to engage. Behavior: hits the draft-outreach edge function which uses an LLM with platform-specific tone profiles (Reddit paragraph, X 280-char reply, YouTube comment, TikTok DM, Instagram caption). Persists nothing. Consumes one credit per draft. Each call is independent; the drafter does not remember previous drafts. Usage: call this once per lead the user picked from a leads.find result. Pick the right outreach_action for the situation: 'comment_post' for a top-level reply on a thread, 'reply_comment' to respond to a specific comment (provide reply_to_author + reply_to_text), 'dm' or 'dm_post_author' for a DM, 'channel_about' for a YouTube About-tab cold intro, 'profile_check' for stale posts where you want a follow-up rather than a direct reply. Do NOT call outreach.draft for COMPETITOR-flagged leads (their matched_signals contains 'category:COMPETITOR') as outreach to a competitor's content is bad form. Do NOT use it to write generic copy unrelated to a specific post. Returns: { draft } as a single string ready to paste, no surrounding chrome.

Build a Week-1 outreach plan from a completed run's HIGH-intent leads, with per-channel send cadence and per-category action register. Behavior: client-side synthesis. Fetches the run via runs.get (no extra credit), buckets HIGH leads (lead_score >= 0.7) by source and matched_signals category, then applies fixed cadence heuristics (Reddit / X tolerate 3-4 sends/day; YouTube / TikTok / Instagram only 2 because each comment is more visible). Idempotent and free. Usage: call this immediately after leads.find completes if the user wants a concrete action plan rather than a raw lead dump. Skip it if HIGH lead count is under 5 (the heuristic falls apart on tiny pools, refine the idea and re-run instead). Do NOT call this on a still-running run, results will be incomplete. Returns: a multi-line text plan with the HIGH/MED/total breakdown, per-channel daily send target + follow-up window, per-category action register (ACTIVE_SEARCH, PAIN_OR_FRUSTRATION, SWITCHING, COMPARISON, FEATURE_GAP, COMPETITOR, TUTORIAL, DISCUSSION), and an end-of-week deprioritisation rule.