| name | research-agent |
| description | Deep research with structured reports and charts. ONLY use when the user explicitly requests research/analysis, or needs data visualization with charts, or quantitative/comparative analysis across multiple sources. Do NOT use for simple questions or quick lookups. |
Research Agent
Autonomous research agent that plans, searches across the web, synthesizes findings, and returns a structured markdown report with citations and charts.
When to use — ALL of these require explicit user intent or clear analytical need
- The user explicitly asks for "research", "report", "analysis", "deep dive", or "investigate"
- The user needs data visualization — charts, graphs, trend plots
- Quantitative or comparative analysis across multiple data points (market sizing, benchmarking, statistical comparisons)
- Multi-section structured reports (literature reviews, competitive analyses, technology surveys)
When NOT to use — default to simpler tools first
- General conversation, Q&A, or factual questions — answer directly
- A single lookup that
wikipedia_search or google_web_search can resolve
- Summarizing a single article or URL — use
fetch_url_content instead
- Code-related tasks — use the
code-agent skill
- Browser automation — use the
browser-automation skill
- Email, calendar, or other tool-based tasks — use the appropriate skill directly
Important: When in doubt, do NOT delegate to research-agent. Use google_web_search or other tools directly. Only escalate to research-agent when the task clearly requires multi-source synthesis, structured reporting, or chart generation.
How to invoke
Call the research_agent tool with a single plan argument. The plan is free-form prose; include:
- Objectives — what the user is trying to learn or decide
- Topics — the specific angles / subtopics to cover
- Structure — the section layout you want in the final report
Example:
research_agent(plan="""
Research Plan: AI Code Assistant Market 2026
Objectives:
- Current market size and growth trends
- Leading products and differentiators
- Enterprise adoption barriers
Topics:
1. Global market statistics and forecasts
2. Top products (Copilot, Cursor, Claude Code, etc.) and positioning
3. Pricing models and enterprise SKUs
4. Security/compliance concerns raised by buyers
Structure:
- Executive Summary (3-5 bullets)
- Market Overview
- Product Landscape
- Enterprise Adoption
- Outlook
""")
The agent streams research_step progress events as it works. The final result is a markdown report saved as a research artifact in the canvas.
Output
- Markdown report with
#/## headings, bullet lists, and inline citations
- Any charts the agent generated are embedded in the markdown
- The full report is also persisted as an
artifacts entry so the user can open it from the canvas
Guidelines for the orchestrator
- Don't fabricate the plan — use the user's own words and just structure them into objectives/topics/structure. If the user only gave a one-line request, expand it into 2-3 objectives but stay true to intent.
- One research_agent call per user request. Don't fan out multiple parallel calls.
- If the user asks a follow-up ("add a section on X", "dig deeper into Y"), call
research_agent again with an updated plan — the agent itself does not have persistent memory across calls.
- After the tool returns, do NOT restate the whole report in chat. The report is already rendered as an artifact; a 1-2 sentence summary pointing the user to the canvas is enough.
