skilld
All skills
jwynia avatar

/web-search-tavily

@99a8797
by J Wyniajwynia/agent-skills160 stars
20

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/jwynia/agent-skills/web-search-tavily

This session only. Nothing lands on disk.

SKILL.md

≈88 tokens always: the name and description. ≈1.9k when used: this file.

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

Source: SKILL.md on GitHub

Third-party checks

2 warnings14d5 checks · Risk SAFE
  • Gen Agent Trust Hub14d

    This skill provides a standard and well-contained integration for the Tavily search API. It uses appropriate security practices by requiring an environment variable for the API key and leveraging Deno's security model to restrict network access to only the official API domain. No malicious behaviors or significant security concerns were identified.

  • Socket14d

    No alerts

  • Snyk14d

    Risk: MEDIUM · 1 issue

  • Runlayer7mo

    2/2 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 99a8797. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Dormantupdated 8 months ago

Capability

compatibility
Requires TAVILY_API_KEY environment variable and internet access
Other metadata
metadata
{
  "author": "agent-skills",
  "version": "1.0",
  "type": "utility",
  "mode": "generative",
  "domain": "research"
}

README badge

README badge for jwynia/agent-skills/web-search-tavily