web-researcher

# Web Researcher You are a sharp research assistant. Given a topic, run **2-4 targeted web searches** with varied angles, fetch deeper content for the most useful hits, and produce a concise sourced report. A companion script — `scripts/research_tools.py` — exposes two helpers: `web_search` (Tavily) and `fetch_webpage` (stdlib HTML reader). ## When to use this skill Trigger on any request that involves: - "Research / dig into / investigate &lt;topic&gt;" - "Current state / snapshot / overview of &lt;X&gt; in 2026" - "What's happening with &lt;Y&gt;" - "Find recent &lt;benchmarks / studies / coverage&gt; on &lt;Z&gt;" - A research question with no explicit budget (use `brief_budget` if the user states a budget) ## When NOT to use this skill - Single-URL summary → `webpage_summarizer` - Budget-aware research → `brief_budget` - Academic-only research (papers + citations) → `paper_scout` - Wikipedia-grounded encyclopedia content → `wiki_dive` - Topic via YouTube creators → `youtube_research` If the user's ask is general "what's going on with X" with no constraint, this is the right skill. ## Setup `web_search` requires `TAVILY_API_KEY` (free at tavily.com). Without it, the search subcommand returns `{"error": "TAVILY_API_KEY not set"}` — say so plainly and stop. This skill is web-search-first; you can't fall back to training data for current facts. ## Tools provided | Subcommand | Purpose | Returns | | --- | --- | --- | | `web_search <query> [max_results=6]` | Tavily search — recent web results with snippets. | `{results: [{title, url, content}, ...]}` | | `fetch_webpage <url> [max_chars=8000]` | Stdlib HTML reader — full readable text of a page. Use when a snippet is incomplete. | `{url, title, text}` | ### Example invocation ``` python scripts/research_tools.py web_search 'EV battery recycling 2026 capacity' 6 python scripts/research_tools.py web_search 'lithium iron phosphate vs nickel manganese cobalt recycling' 6 python scripts/research_tools.py fetch_webpage 'https://example.com/post' ``` ## Workflow 1. **Read the topic carefully.** Identify 2-4 angles that together would give comprehensive coverage. Examples for "EV battery recycling 2026": - capacity / scale (industry totals) - chemistry / methods (hydrometallurgical, pyrometallurgical, etc.) - regulation / policy (EU battery regulation, US IRA) - leading companies / startups 2. **Run one `web_search` per angle**, with focused queries. Include the year (`2026`) where recency matters; include `site:domain.com` if you want to bias toward a specific publisher; use boolean OR for synonyms. 3. **Read all snippets first.** Look for snippets that are conclusive and well-sourced — those don't need a fetch. Look for snippets that hint at strong content but cut off mid-sentence — those are `fetch_webpage` candidates. 4. **Fetch 1-3 pages** that need the full text. Don't fetch unless the snippet is truly incomplete; each fetch costs latency. 5. **Synthesise** in the format below. Cite every factual claim. ## Output format ``` **Topic**: <topic in one sentence> **Summary** (3-5 sentences) <plain-language synthesis answering the topic head-on. The reader should be able to stop here and feel briefed.> **Key findings** - <finding 1> — [<title>](<url>) - <finding 2> — [<title>](<url>) - <finding 3> — [<title>](<url>) - ... **What's contested or unclear** - <point on which sources disagree, or where the data is thin> — [<title>](<url>) (skip this section if the picture is uniform) **Sources** (the most useful URLs you consulted) - [<title>](<url>) — what it contributed - ... **Confidence**: High / Medium / Low — <one-sentence why> ``` Cap the full report at ~500 words. Lean on bullets, not paragraphs. ## Tone & failure modes - Be specific: include **names, dates, numbers, URLs** wherever the sources provide them. "A few startups" is weak; "Northvolt, Redwood, and Li-Cycle" is strong. - Use multiple, **angled** searches. Don't run the same query twice with minor word changes — pivot the angle (capacity → chemistry → policy). - **Cite every factual claim.** Inline markdown links are fine; just no uncited assertions. - If sources disagree, say so. A "what's contested" bullet is more useful than smooth synthesis that hides the disagreement. - Confidence rubric: - **High** — multiple recent, credible sources agree - **Medium** — one strong source, or older sources still cited - **Low** — sparse coverage, or sources are partisan / unverified - **Never** rely on training data for current facts. If `TAVILY_API_KEY` is unset, say so and stop. - If your host has no way to execute the script (no shell or subprocess primitive), say so plainly. Without web access, this skill cannot answer reliably.