> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Optimized retrieval primitives for research agents: search, crawl, extract, and social media.

Each tool combines Tavily API endpoints with context engineering — formatting results for LLMs, managing token limits, deduplicating sources, and cleaning web noise. Your agent focuses on reasoning while the tools handle retrieval complexity.

| Scenario                                    | Tool                    |
| ------------------------------------------- | ----------------------- |
| "Answer this question with web research"    | `search_and_answer`     |
| "Research this topic from multiple angles"  | `search_dedup`          |
| "What does this website say?"               | `crawl_and_summarize`   |
| "Summarize these specific pages"            | `extract_and_summarize` |
| "What are people saying on Reddit/Twitter?" | `social_media_search`   |

***

## `search_and_answer`

Answer a question using web research. Optionally generates subqueries for comprehensive coverage, handles token limits, and synthesizes an answer with your chosen model.

### Parameters

| Parameter                  | Type         | Default   | Description                               |
| -------------------------- | ------------ | --------- | ----------------------------------------- |
| `query`                    | str          | Required  | The question to answer                    |
| `api_key`                  | str          | Required  | Tavily API key                            |
| `model_config`             | ModelConfig  | None      | LLM configuration for synthesis           |
| `max_number_of_subqueries` | int          | 2-4       | Number of subqueries to generate          |
| `output_schema`            | OutputSchema | None      | Pydantic model for structured output      |
| `token_limit`              | int          | 50000     | Maximum token budget for context          |
| `threshold`                | float        | 0.3       | Minimum relevance score                   |
| `topic`                    | str          | "general" | `"general"`, `"news"`, or `"finance"`     |
| `time_range`               | str          | None      | `"day"`, `"week"`, `"month"`, or `"year"` |
| `include_domains`          | list         | None      | Only search these domains                 |
| `exclude_domains`          | list         | None      | Exclude these domains                     |

### Example

```python theme={null}
from tavily_agent_toolkit import search_and_answer, ModelConfig, ModelObject

result = await search_and_answer(
    query="What are the pros and cons of Rust vs Go?",
    api_key="tvly-xxx",
    model_config=ModelConfig(model=ModelObject(model="anthropic:claude-sonnet-4-5")),
    max_number_of_subqueries=3,
)
print(result["answer"])
```

***

## `search_dedup`

Run multiple search queries in parallel and consolidate results. Deduplicates by URL and merges content chunks from the same source.

### Parameters

| Parameter           | Type       | Default    | Description                               |
| ------------------- | ---------- | ---------- | ----------------------------------------- |
| `queries`           | list\[str] | Required   | List of search queries                    |
| `api_key`           | str        | Required   | Tavily API key                            |
| `search_depth`      | str        | "advanced" | `"basic"` or `"advanced"`                 |
| `topic`             | str        | "general"  | `"general"`, `"news"`, or `"finance"`     |
| `max_results`       | int        | 5          | Results per query                         |
| `chunks_per_source` | int        | 3          | Content chunks per source                 |
| `time_range`        | str        | None       | `"day"`, `"week"`, `"month"`, or `"year"` |
| `include_domains`   | list       | None       | Only search these domains                 |
| `exclude_domains`   | list       | None       | Exclude these domains                     |

### Example

```python theme={null}
from tavily_agent_toolkit import search_dedup

results = await search_dedup(
    api_key="tvly-xxx",
    queries=[
        "transformer architecture explained",
        "attention mechanism neural networks",
        "BERT GPT comparison",
    ],
    search_depth="advanced",
    max_results=5,
)

for r in results["results"]:
    print(f"{r['title']}: {r['score']}")
```

***

## `crawl_and_summarize`

Crawl an entire website and summarize the content with your chosen model. Useful for documentation sites, knowledge bases, or product catalogs.

### Parameters

| Parameter       | Type         | Default  | Description                                   |
| --------------- | ------------ | -------- | --------------------------------------------- |
| `url`           | str          | Required | Website URL to crawl                          |
| `model_config`  | ModelConfig  | Required | LLM for summarization                         |
| `api_key`       | str          | Required | Tavily API key                                |
| `instructions`  | str          | None     | Specific extraction instructions              |
| `output_schema` | OutputSchema | None     | Pydantic model for structured output          |
| `max_depth`     | int          | 1-5      | How deep to crawl from starting URL           |
| `max_breadth`   | int          | 20       | Max pages to crawl per level                  |
| `limit`         | int          | 50       | Total max pages to crawl                      |
| `select_paths`  | list         | None     | Only crawl URLs matching these regex patterns |
| `exclude_paths` | list         | None     | Skip URLs matching these regex patterns       |

### Example

```python theme={null}
from tavily_agent_toolkit import crawl_and_summarize, ModelConfig, ModelObject

result = await crawl_and_summarize(
    url="https://docs.example.com",
    model_config=ModelConfig(model=ModelObject(model="anthropic:claude-sonnet-4-20250514")),
    instructions="Extract all API endpoints and their parameters",
    api_key="tvly-xxx",
    max_depth=2,
    select_paths=["/docs/.*", "/api/.*"],
)
print(result["summary"])
```

***

## `extract_and_summarize`

Extract content from specific URLs and summarize with your model. Use when you already know which pages have the information.

### Parameters

| Parameter           | Type         | Default  | Description                                |
| ------------------- | ------------ | -------- | ------------------------------------------ |
| `urls`              | list\[str]   | Required | URLs to extract (max 20)                   |
| `model_config`      | ModelConfig  | Required | LLM for summarization                      |
| `api_key`           | str          | Required | Tavily API key                             |
| `query`             | str          | None     | Focuses extraction on specific information |
| `output_schema`     | OutputSchema | None     | Pydantic model for structured output       |
| `chunks_per_source` | int          | 5        | Content chunks per source                  |
| `extract_depth`     | str          | "basic"  | `"basic"` or `"advanced"`                  |

### Example

```python theme={null}
from tavily_agent_toolkit import extract_and_summarize, ModelConfig, ModelObject

result = await extract_and_summarize(
    urls=["https://en.wikipedia.org/wiki/Artificial_intelligence"],
    model_config=ModelConfig(model=ModelObject(model="groq:llama-3.3-70b-versatile")),
    query="What are the main ethical concerns with AI?",
    api_key="tvly-xxx",
    chunks_per_source=5,
)
print(result["results"][0]["summary"])
```

***

## `social_media_search`

Search specific social platforms for discussions and content.

### Parameters

| Parameter             | Type | Default    | Description                                                                               |
| --------------------- | ---- | ---------- | ----------------------------------------------------------------------------------------- |
| `query`               | str  | Required   | Search query                                                                              |
| `api_key`             | str  | Required   | Tavily API key                                                                            |
| `platform`            | str  | "combined" | `"reddit"`, `"x"`, `"linkedin"`, `"tiktok"`, `"instagram"`, `"facebook"`, or `"combined"` |
| `include_raw_content` | bool | False      | Include full post content                                                                 |
| `max_results`         | int  | 5          | Number of results                                                                         |
| `time_range`          | str  | None       | `"day"`, `"week"`, `"month"`, or `"year"`                                                 |

### Example

```python theme={null}
from tavily_agent_toolkit import social_media_search

results = social_media_search(
    query="best practices for LLM fine-tuning",
    api_key="tvly-xxx",
    platform="reddit",
    max_results=10,
    time_range="month",
)
```

***

## Model Configuration

All tools that use an LLM accept a `ModelConfig`. Use the `"provider:model"` format, and optionally specify fallback models:

```python theme={null}
from tavily_agent_toolkit import ModelConfig, ModelObject

config = ModelConfig(
    model=ModelObject(model="openai:gpt-5.2"),
    fallback_models=[
        ModelObject(model="anthropic:claude-sonnet-4-20250514"),
        ModelObject(model="groq:llama-3.3-70b-versatile"),
    ],
    temperature=0.7,
)
```

**Retry behavior:**

* With `fallback_models`: each model gets 1 attempt before moving to the next
* Without `fallback_models`: primary model gets 1 retry (2 attempts total)

See the [GitHub README](https://github.com/tavily-ai/tavily-cookbook/tree/main/agent-toolkit#model-configuration) for the full list of 20+ supported providers.