Agent-Skills.md

Agent Skills: Web Search (Tavily API)

Search the web using Tavily API for high-quality, AI-optimized results with advanced filtering options. Use when you need structured search results, domain filtering, relevance scores, or AI-generated answer summaries. Requires TAVILY_API_KEY. Keywords: tavily, advanced search, filtered search, domain filtering, relevance scoring.

UncategorizedID: jwynia/agent-skills/web-search-tavily

Repository

jwynia/agent-skills
jwynia
388

Install this agent skill to your local

pnpm dlx add-skill https://github.com/jwynia/agent-skills/tree/HEAD/skills/general/research/tools/web-search-tavily

Skill Files

Browse the full folder contents for web-search-tavily.

Download Skill

Loading file tree…

skills/general/research/tools/web-search-tavily/SKILL.md

Skill Metadata

Name
web-search-tavily
Description
"Search the web using Tavily API for high-quality, AI-optimized results with advanced filtering options. Use when you need structured search results, domain filtering, relevance scores, or AI-generated answer summaries. Requires TAVILY_API_KEY. Keywords: tavily, advanced search, filtered search, domain filtering, relevance scoring."

Web Search (Tavily API)

Search the web using Tavily's AI-optimized search API. Returns high-quality, structured results with relevance scores and optional AI-generated summaries.

Note: This skill requires a Tavily API key. For basic web search using the agent's built-in capability, see web-search.

When to Use This Skill

Use this skill when:

  • You need to find current information not in your training data
  • The user asks about recent events, news, or updates
  • You need to verify facts or find authoritative sources
  • Research requires real-time web data
  • Keywords mentioned: search, look up, find online, current, latest, news

Do NOT use this skill when:

  • Information is already in your knowledge base and doesn't need verification
  • The user asks about historical facts that don't change
  • You're working with local files or code (use other tools)
  • A more specific skill exists for the task (e.g., documentation lookup)

Prerequisites

Before using this skill, ensure:

  • TAVILY_API_KEY environment variable is set with a valid API key
  • Deno is installed (for running the search script)
  • Internet access is available

Get a Tavily API key at: https://tavily.com

Quick Start

Run a simple search:

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "your search query"

Example with AI-generated answer:

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "React 19 new features" --answer

Script Usage

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts [options] "query"

Options

| Option | Description | Default | |--------|-------------|---------| | --answer | Include AI-generated answer summary | false | | --depth <level> | Search depth: basic or advanced | basic | | --results <n> | Number of results to return | 5 | | --topic <type> | Topic type: general, news, or finance | general | | --time <range> | Time filter: day, week, month, or year | none | | --include <domains> | Only include these domains (comma-separated) | none | | --exclude <domains> | Exclude these domains (comma-separated) | none | | --raw | Include raw page content in results | false | | --json | Output as JSON (for programmatic use) | false | | --help | Show help message | - |

Search Parameters

Topic Types

  • general (default): Broad web search across all content types
  • news: Prioritizes news articles and current events
  • finance: Focuses on financial information and market data

Search Depth

  • basic (default): Fast search, good for most queries
  • advanced: Deeper search with more comprehensive results (slower, higher API cost)

Time Range

Filter results by recency:

  • day: Last 24 hours
  • week: Last 7 days
  • month: Last 30 days
  • year: Last 365 days

Domain Filtering

Control which sites appear in results:

# Only search documentation sites
scripts/search.ts "React hooks" --include docs.react.dev,developer.mozilla.org

# Exclude social media
scripts/search.ts "AI news" --exclude twitter.com,reddit.com

Output Format

Human-Readable Output (default)

🔍 Search: "React 19 new features"

Found 5 results in 234ms

📝 AI Answer:
────────────────────────────────────────────────────────────
React 19 introduces several new features including...
────────────────────────────────────────────────────────────

1. React 19 Release Notes
   https://react.dev/blog/2024/04/25/react-19
   React 19 is now available on npm! This release includes...
   Score: 0.987

2. What's New in React 19
   https://example.com/react-19-features
   A comprehensive overview of React 19's new features...
   Score: 0.945

JSON Output (--json)

{
  "query": "React 19 new features",
  "results": [
    {
      "title": "React 19 Release Notes",
      "url": "https://react.dev/blog/2024/04/25/react-19",
      "content": "React 19 is now available on npm...",
      "score": 0.987,
      "published_date": "2024-04-25"
    }
  ],
  "answer": "React 19 introduces several new features...",
  "response_time": 234
}

Result Fields

| Field | Type | Description | |-------|------|-------------| | title | string | Page title | | url | string | Source URL | | content | string | Relevant excerpt from the page | | score | number | Relevance score (0-1, higher is better) | | published_date | string | Publication date (if available) | | raw_content | string | Full page content (only with --raw) |

Examples

Example 1: Current Events Search

Scenario: Find recent news about a technology topic

scripts/search.ts "OpenAI GPT-5 announcement" --topic news --time week --answer

Expected output: Recent news articles about GPT-5, with an AI-generated summary

Example 2: Documentation Lookup

Scenario: Find specific technical documentation

scripts/search.ts "Deno deploy edge functions tutorial" --depth advanced --results 10

Expected output: Comprehensive results from documentation and tutorial sites

Example 3: Fact Verification

Scenario: Verify a specific claim or statistic

scripts/search.ts "world population 2024" --include un.org,worldbank.org,census.gov --json

Expected output: JSON results from authoritative sources for programmatic verification

Example 4: Financial Research

Scenario: Research market information

scripts/search.ts "NVIDIA stock analysis 2024" --topic finance --answer

Expected output: Financial analysis and market data with AI summary

Common Issues and Solutions

Issue: "TAVILY_API_KEY environment variable is not set"

Symptoms: Script exits immediately with API key error

Solution:

  1. Get an API key from https://tavily.com
  2. Set the environment variable: 
    export TAVILY_API_KEY="your-api-key-here"
  3. Or run with the variable inline: 
    TAVILY_API_KEY="your-key" deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "query"

Issue: "Invalid Tavily API key"

Symptoms: 401 authentication error

Solution:

  1. Verify your API key is correct (no extra spaces)
  2. Check if your API key has expired
  3. Verify your Tavily account is active

Issue: "Tavily API rate limit exceeded"

Symptoms: 429 error response

Solution:

  1. Wait a moment and retry
  2. Reduce request frequency
  3. Consider upgrading your Tavily plan for higher limits

Issue: No results returned

Symptoms: Empty results array

Solution:

  1. Try broader search terms
  2. Remove domain filters that might be too restrictive
  3. Check if the topic exists online
  4. Try --depth advanced for harder queries

Limitations

This skill has the following limitations:

  • Requires active internet connection
  • API rate limits apply based on your Tavily plan
  • Results depend on Tavily's index coverage
  • Cannot access paywalled or login-required content
  • Real-time accuracy depends on Tavily's crawling frequency
  • Maximum query length and result count have API limits

Related Skills

  • research-workflow: For comprehensive research projects that use multiple searches with planning and synthesis