---
name: tavily-search
description: Web search via Tavily for frequent daily use. Use when the user says Tavily, when Brave/Perplexity web_search is unavailable, or when you want stable search results with snippets and links. Reads the Tavily API key from Bitwarden item openclaw/tavily (login.password) using a fresh .bw_session, and falls back to built-in web_search when Tavily quota/errors occur.
---

## How to use

Prefer Tavily (REST) as primary search.

Run:

```bash
python3 skills/tavily-search/scripts/tavily_search.py --query "<query>" --max-results 5
```

### Secret handling (must follow)

- Never paste the Tavily API key into chat.
- Preferred: store the key in OpenClaw config `env.vars.TAVILY_API_KEY` (so day-to-day use does **not** depend on Bitwarden unlock).
- Fallback key resolution order:
  1) `TAVILY_API_KEY` env var
  2) `BW_SESSION` env var + Bitwarden item `openclaw/tavily`
  3) local file `/home/kuhnn/.openclaw/.bw_session` (only if fresh; 1h janitor already exists)

### Cost / quota safety

- Local monthly counter defaults to 2000 calls/month and will return `monthly_cap_reached` when reached.
- Use cache (default TTL 1h) to reduce calls.

### Fallback logic (agent behavior)

If Tavily returns an error / cap reached, fall back to built-in `web_search` (Brave/Perplexity) if configured.

### Output

The script outputs JSON from Tavily, plus:
- `_cache`: hit/miss
- `_usage`: year/month tag

When replying to the user:
- Return 3–6 results max.
- Format as bullet list for Telegram/WhatsApp (no markdown tables).