deep-research

# Gemini Deep Research > **Local addition (cli-jaw-skills).** Method ownership: `jaw-search/references/deep-research.md` > owns how a deep-research task is scoped, tracked and reported. This skill is one > execution backend for it — the report format below is that backend's output format, > not the protocol. Autonomous research agent that plans searches, reads sources, and synthesizes cited reports. ## When to Use - Questions requiring synthesis across many sources (market analysis, literature reviews, competitive landscape) - Due diligence or technical research where breadth matters more than speed - NOT for quick factual lookups (use `search` skill instead) Trade-off: higher cost and latency in exchange for comprehensive, cited coverage. ## Requirements - Python 3.8+, httpx (`pip install -r requirements.txt`) - `GEMINI_API_KEY` environment variable ## CLI Reference ```bash python3 scripts/research.py --query "..." [options] ``` | Flag | Effect | |------|--------| | `--query "..."` | Research question (required for new tasks) | | `--format "..."` | Output structure template | | `--stream` | Stream progress in real-time | | `--no-wait` | Start task and return immediately | | `--status <id>` | Check status of a running task | | `--wait <id>` | Block until task completes | | `--continue <id>` | Follow-up on previous research | | `--list` | List recent research tasks | | `--json` | Output as structured JSON | | `--raw` | Output raw API response | ## Cost and Latency Costs and times vary by query complexity and source count. Expect minutes, not seconds. Check actual token usage in the output metadata for accurate billing. ## Exit Codes - **0**: Success - **1**: Error (API, config, or timeout) - **130**: Cancelled (Ctrl+C) --- ## MCP-Based Web Research When firecrawl or exa MCP servers are available, use them as complementary search sources alongside the Gemini agent. ### Available MCP Tools | Server | Tools | Best For | |--------|-------|----------| | firecrawl | `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl` | Broad web search, full-page scraping | | exa | `web_search_exa`, `web_search_advanced_exa`, `crawling_exa` | Semantic search, date-filtered results | ### Multi-Source Search Strategy For each research sub-question: 1. Use 2–3 keyword variations per sub-question. 2. Search with each available tool (firecrawl + exa for best coverage). 3. Deep-read 3–5 key sources with `firecrawl_scrape` or `crawling_exa` — search snippets alone are insufficient. 4. Aim for 15–30 unique sources across all sub-questions. Source priority: academic papers, official docs > reputable news > blogs > forums. ### Date-Filtered Search (exa) ``` web_search_advanced_exa(query: "...", numResults: 5, startPublishedDate: "2025-01-01") ``` Use date filters for fast-moving topics (AI, policy, markets). ## Report Format ```markdown # [Topic]: Research Report *Generated: [date] | Sources: [N] | Confidence: [High/Medium/Low]* ## Executive Summary [3–5 sentence overview of key findings] ## 1. [Theme] [Findings with inline citations] - Key point ([Source](url)) - Supporting data ([Source](url)) ## 2. [Theme] ... ## Key Takeaways - [Actionable insight 1] - [Actionable insight 2] ## Sources 1. [Title](url) — [one-line summary] 2. ... ## Methodology Searched [N] queries across [tools used]. Analyzed [M] sources. Sub-questions: [list] ``` Short topics: deliver full report inline. Long reports: executive summary + key takeaways inline, full report saved to file. ## Multi-Source Triangulation 1. **Every claim needs a source.** No unsourced assertions. 2. **Cross-reference**: if only one source says it, flag as unverified. 3. **Recency**: prefer sources from the last 12 months for fast-moving topics. 4. **Acknowledge gaps**: if a sub-question has poor coverage, say so explicitly. 5. **Separate fact from inference**: label estimates, projections, and opinions clearly. ## Parallel Research with Subagents For broad topics, launch parallel explore/research agents per sub-question cluster: - Agent 1: sub-questions 1–2 - Agent 2: sub-questions 3–4 - Agent 3: cross-cutting themes + synthesis prep Each agent searches, reads sources, and returns structured findings. The main session synthesizes into the final report.