deep-research

Deep Research

Call tavily_research to produce a cited multi-source report. This is the marquee Cowork research skill — slow but high-quality.

When to use this skill

• The user wants a report, not a snippet.
• The question requires synthesis across many sources.
• "Compare X vs Y vs Z" — multi-entity research.
• Market analysis, literature review, briefing materials.
• The user is preparing for a meeting, decision, or write-up.

For quick fact lookups, use web-search. For pulling content from a known URL, use extract-page. For competitor-specific research, prefer competitive-intel — it has competitor-shaped scaffolding on top.

Set expectations first

This call takes 30–120 seconds. Always tell the user before kicking it off, with a one-line preview of what you're about to research and roughly how long it'll take. Cowork users hate silence.

Example: "Researching the competitive landscape for AI code assistants — this'll take about a minute. I'll come back with a cited report."

How to call the tool

Pass these arguments to tavily_research:

Argument	When to set it
query	Required. The research question. Phrase it as a clear question or topic, not a search query.
model	mini, pro, or auto (default). See selection guide below.
output_schema	Optional JSON schema. Use when the user wants structured output (e.g. a comparison table).
citation_format	numbered (default), mla, apa, chicago. Match the user's downstream context.
stream	Bool. Stream tokens as the report builds — better UX for the user.
timeout	Max wait seconds. Default 600.

Model selection

Question shape	Model
"What does X do?", single-topic explainer	mini (~30s)
"X vs Y vs Z", "comprehensive analysis", "market report on…", "best way to…"	pro (~60–120s)
Unclear or mixed	auto

Default to pro when the user's request looks report-shaped; default to mini for explainers and single-entity briefs. Don't burn pro on a question web-search could answer.

Structured output

When the user wants a comparison table or fixed-shape report, pass an output_schema so Tavily returns JSON instead of prose. Example schema for a competitor comparison:

{
  "type": "object",
  "properties": {
    "competitors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "positioning": {"type": "string"},
          "pricing": {"type": "string"},
          "differentiators": {"type": "array", "items": {"type": "string"}},
          "weaknesses": {"type": "array", "items": {"type": "string"}}
        }
      }
    }
  }
}

Then format the JSON into a markdown table for the user.

Returning results

Default deliverable shape:

1. Executive summary — 3–5 sentences, the answer the user is here for.
2. Body — sectioned by sub-topic with inline citations.
3. Sources — numbered list of URLs, matching citation numbers in the body.
4. Open questions — what the report couldn't answer, where the user might want to dig deeper.

When the user asks for a deliverable, save the report as a markdown file to ~~document store (or to the workspace folder if no document store is connected). Keep the chat reply to the executive summary plus a link.

Patterns and prompting

• Be specific in the query: "competitive landscape for AI coding assistants in 2025, focusing on enterprise adoption" beats "AI code tools".
• Multi-entity comparisons: list every entity in the query so the agent gives each equal coverage.
• Time-bound queries: include the year and recency window in the query — "…trends in Q1 2025".
• Audience cue: tell the agent who the report is for (e.g. "for an engineering exec audience"). It changes tone and depth.

Failure modes

• Times out: bump timeout, or simplify the query into 2–3 sub-queries and synthesize manually.
• Generic, low-value report: query was too broad. Re-run with a narrower scope and named entities.
• Missing citations: should be rare — if it happens, re-run with citation_format: "numbered" explicitly set.

For comparison-table templates and audience-tuning prompts, see references/research-templates.md.