/tinyfish-social-listening

name: tinyfish-social-listening
description: Monitor brand mentions, sentiment, and industry chatter across the web using TinyFish Search and Fetch. Use when a user asks to track what people are saying about a brand, product, or topic, run social listening, or get a pulse on public perception. If the user already named the target, proceed directly. Default time window is last 7 days. Always link every claim to its source URL.

Social Listening with TinyFish

Track brand mentions, sentiment, and industry chatter across the live web — forums, blogs, news, social platforms, and developer communities — using TinyFish Search and Fetch.

**First step:** If the user already named the brand/topic, proceed directly. Otherwise, ask. **Default time window:** Last 7 days. **Always link every claim to its source URL.**

When To Use

• User wants to know what people are saying about a brand, product, person, or topic.
• User asks to monitor competitors or compare share of voice.
• User wants sentiment analysis on a launch, feature, controversy, or trend.
• User says "social listening," "brand monitoring," "reputation check," "buzz check," or "what's the internet saying about X."
• User wants a recurring pulse on public perception (pair with a cron job).

Pre-flight Check (REQUIRED)

# 1. TinyFish CLI installed?
which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"

# 2. Authenticated?
tinyfish auth status

If CLI is not available, fall back to the TinyFish API with `TINYFISH_API_KEY`:

test -n "$TINYFISH_API_KEY" && echo "API_KEY_AVAILABLE" || echo "NO_TINYFISH_ACCESS"

If neither works, stop and tell the user to install or authenticate.

---

Core Workflow

Step 1 — Identify the target

If the user already named the brand/topic, skip asking and proceed. Otherwise, ask what brand, product, or topic they want to research. Then set:

• **Target entity:** Whatever the user specifies.
• **Time focus:** Last 7 days. All search queries MUST include date constraints.
• **Channels:** Reddit, Hacker News, Twitter/X, LinkedIn, blogs, news, GitHub, forums, YouTube.
• **Sentiment lens:** General pulse.

**⚠️ CRITICAL: STRICT 7-DAY ENFORCEMENT ⚠️** Search engines regularly return results older than 7 days regardless of date constraints in queries. You MUST: 1. Check the `published_date` field on every fetched result 2. Check date indicators in Reddit posts (e.g., "7d ago", "2mo ago") and other platforms 3. **DISCARD any result older than 7 days from today** — do NOT include it in the report, do NOT quote it, do NOT use it for sentiment classification 4. If most results are older than 7 days, say so honestly: "Limited discussion found in the last 7 days" 5. NEVER silently widen the window — if the 7-day window is thin, report that it's thin 6. In the final report, every source MUST have its date stated. Any source without a verifiable date within the last 7 days gets excluded.

Step 1.5 — Resolve X/Twitter handle (MANDATORY before any searches)

**⛔ Do NOT guess the X handle. Do NOT skip this step.**

Run a single search to find the brand's verified X handle:

tinyfish search query "{brand} site:x.com"

Look at the profile URLs that come back (e.g., `x.com/Tiny_Fish`, `x.com/sudheenair`). Extract the **primary brand handle** — this is the one you'll use in all X queries below. Also note any key people handles (CEO, founders) for additional queries.

**Store the result:** `VERIFIED_HANDLE={handle}` — use this variable mentally for all X queries. If no profile URL comes back, note that X coverage will be limited.

Step 2 — Run multi-angle searches

Run **parallel searches** across different angles. For most platforms, include date strings (e.g., `{current month year}`) to help narrow results. **⛔ EXCEPTION: X/Twitter queries MUST NOT include date strings** — tweets don't contain "2026" or "May 2026" in their text, so adding date strings causes the search engine to filter out real tweets before they reach you. Use snowflake decoding to date-gate X results AFTER they come back. This is the #1 cause of missing X coverage — the agent adds year/month to every query, search engines match on page text, and tweets silently disappear from results.

2a — X/Twitter searches (MANDATORY — all 3 patterns REQUIRED)

**⛔ This is a separate mandatory block, not optional. All 3 query patterns below MUST run. The agent has historically skipped these and missed 80%+ of X activity as a result.**

Generic `site:x.com "{brand}"` queries return mostly **profile page URLs** (undateable, useless). The following 3 patterns are specifically designed to return individual tweet URLs with `/status/` IDs that can be snowflake-decoded:

# PATTERN 1: Brand's own tweets (returns /status/ URLs)
# ⛔ NO date strings — tweets don't contain "2026" in text. Snowflake-decode dates after.
tinyfish search query "x.com/{VERIFIED_HANDLE}/status"
tinyfish search query "site:x.com/{VERIFIED_HANDLE}/status"

# PATTERN 2: Anyone tagging the brand (returns /status/ URLs from other users)
tinyfish search query "\"@{VERIFIED_HANDLE}\" site:x.com"
tinyfish search query "@{VERIFIED_HANDLE} site:x.com"

# PATTERN 3: Organic mentions by name without tagging (people discussing the brand in tweet text)
tinyfish search query "site:x.com \"{brand}\""
tinyfish search query "site:x.com \"{brand}.ai\""

# PATTERN 4: Product-specific keywords (mine earlier snippets for these)
tinyfish search query "site:x.com {brand} {product_keyword}"

**Verification gate:** After running all 3 patterns, count how many unique `/status/` URLs you got. If fewer than 5, run additional queries using product-specific keywords found in the brand's recent announcements or from earlier search snippets (e.g., product names, feature launches, event names). Profile-page snippets from generic searches often contain recent tweet text — mine those for keywords to construct targeted follow-up queries.

Also r