# Research Skill — Tavily Four-Tier Toolset

This skill documents the four Tavily research tools available to the researcher subagent,
their parameters, decision framework, and output format.

---

## Tools

### 1. `web_search` — Simple factual queries
Use for quick, direct factual lookups. Minimal parameters.

| Parameter | Type   | Description                    |
|-----------|--------|--------------------------------|
| query     | string | The search query               |
| count     | int    | Number of results (default: 5) |

**When to use:** Single-fact questions, quick lookups, entity identification.

---

### 2. `tavily_search` — Filtered web search
Use for targeted searches with domain, topic, and time filtering.

| Parameter        | Type    | Values / Notes                                     |
|------------------|---------|----------------------------------------------------|
| query            | string  | Search query                                       |
| search_depth     | string  | `"basic"` (fast) \| `"advanced"` (thorough)        |
| topic            | string  | `"general"` \| `"news"` \| `"finance"`             |
| time_range       | string  | `"day"` \| `"week"` \| `"month"` \| `"year"`       |
| include_domains  | list    | Restrict to these domains                          |
| exclude_domains  | list    | Exclude these domains                              |
| include_answer   | bool    | Include AI-generated answer summary                |
| max_results      | int     | 1–20 results                                       |

**When to use:** You need filtered, current, or domain-specific results.

---

### 3. `tavily_extract` — Extract content from URLs
Use when you already have URLs and need their full content.

| Parameter      | Type   | Values / Notes                              |
|----------------|--------|---------------------------------------------|
| urls           | list   | List of URLs to extract                     |
| extract_depth  | string | `"basic"` \| `"advanced"`                  |
| query          | string | Focus string — improves extraction relevance|
| include_images | bool   | Include image URLs from page                |

**When to use:** You have specific URLs (from search results, user-provided, or prior research).

---

### 4. `tavily_research` — AI deep research agent
For complex synthesis across multiple sources. Calls the Tavily Research API.

**Script:** `~/.config/agents/skills/research/scripts/tavily-research.sh`

```
Usage: tavily-research.sh "question" [mini|pro|auto] [numbered|apa|mla|chicago]
```

| Argument        | Values                          | Default    |
|-----------------|---------------------------------|------------|
| question        | Research question (required)    | —          |
| model           | `mini` \| `pro` \| `auto`       | `auto`     |
| citation_format | `numbered` \| `apa` \| `mla` \| `chicago` | `numbered` |

Model guidance:
- `mini` — fast, lower cost, suitable for simple synthesis
- `pro`  — comprehensive, higher quality, use for deep analysis
- `auto` — Tavily selects based on query complexity

**When to use:** Multi-source synthesis, complex analytical questions, research reports.

---

## Decision Framework

```
Is the question a simple fact?
  → YES → web_search (fast, minimal tokens)

Do you already have URLs to extract?
  → YES → tavily_extract

Do you need domain/topic/time filtering?
  → YES → tavily_search (set search_depth, topic, time_range as needed)

Is this a complex synthesis requiring multiple sources?
  → YES → tavily_research (model=pro for thoroughness)
```

---

## Output Format Template

```markdown
# [Topic] — Research Report
*Generated: YYYY-MM-DD | Sources: N*

## Summary
[2–3 sentence executive summary]

## Key Findings
1. [Finding with citation [1]]
2. [Finding with citation [2]]
...

## Analysis
[Deeper synthesis, 2–5 paragraphs]

## Sources
[1] Title — URL
[2] Title — URL
...
```

**Save path:** `~/.openclaw/workspace/SarvisVault/YYYYMMDD_TopicSlug.md`