tavily-search

Tavily Search

Cheap, fast, agent-native web search. Returns clean LLM-optimized results with source URLs.

When to use

• Broad web research on a topic you don't already know
• Gathering article links + summaries for a writing piece
• Verifying recent facts without loading entire pages into context
• Any task where web_fetch across many URLs would cost 10-100x more tokens for the same signal

Use web_fetch instead when: you already have the exact URL and need the full page content. Use Perplexity instead when: you need a synthesized, opinionated answer (not raw search hits).

First-time setup

This skill calls a Supabase edge function that wraps the Tavily API. Setup takes about 10 minutes:

1. Get a free Tavily API key at https://tavily.com.
2. Install the supabase-builder plugin from this marketplace.
3. Follow references/build-prompt.md — paste the prompt into cowork and supabase-builder generates + deploys the edge function in your own Supabase.

After setup, the function lives at https://<your-project>.supabase.co/functions/v1/tavily-search with bearer-auth protection.

Call pattern

POST https://<your-project>.supabase.co/functions/v1/tavily-search
Authorization: Bearer <your-supabase-anon-key>
Content-Type: application/json

{
  "query": "<search query>",
  "max_results": 5,
  "include_answer": true,
  "topic": "general",
  "time_range": null
}

Returns:

{
  "answer": "<direct answer if include_answer=true>",
  "results": [
    { "title": "...", "url": "...", "content": "...", "score": 0.92 }
  ]
}

Flow

1. User says "research " or similar trigger phrase.
2. Craft a focused Tavily query. Shorter + more specific = better results.
3. Call the edge function with max_results: 5 as the default.
4. Surface the top 3-5 results: title, URL, one-line summary.
5. If the user wants a deep read on one specific result, use web_fetch for that single URL.

Guardrails

• Never paste the Tavily API key in chat. It lives in Supabase secrets (TAVILY_API_KEY). The edge function reads it.
• Rate limit: 100 requests/min on Tavily's free tier. Plenty for interactive use.
• Cost check: each call costs ~1-2 Tavily API credits. Orders of magnitude cheaper than multiple web_fetch calls for the same topic.
• Fallback: if the edge function errors (500 / timeout / network), retry once, then fall back to web_fetch for a single representative URL.
• Never store search results in the coworker workspace without summarization first. Raw Tavily output can bloat files fast.

Upgrade path

For meaning-rich research (fact-checking, topic synthesis, "what is X and why does it matter"):

• Add a Perplexity API edge function using the same supabase-builder pattern.
• Perplexity returns opinionated, synthesized answers. Tavily returns raw search hits.
• Rule of thumb: Tavily for "find me articles about X." Perplexity for "explain X to me with citations."