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 synthesispro— comprehensive, higher quality, use for deep analysisauto— 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
# [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