A research report is a cited study of a niche or an offer, written for paid advertising: who buys, what they search for, what competitors promise, the exact words customers use, their objections and the angles worth testing. Your agent starts it over MCP, granvl files the finished report in Research, and your agent reads it before it writes pages and ads.
Before you begin
Connect your agent to granvl. See Connect your agent.
Research runs on Tool credits. Your workspace needs enough credits to cover the estimate before a run starts. See Tool credits.
Start a research report
Ask your agent for research. Name the offer or the niche, and the market: the country, plus the city for a local business.
Your agent asks granvl for an estimate first. Nothing runs and nothing is charged. It tells you the credits and the expected minutes.
Say yes. The run starts and your agent shows you a quick read (a short, cited summary) right away.
Your agent checks the run about every two minutes. A deep run usually takes 5 to 25 minutes, a standard run 2 to 10.
When the run finishes, granvl files the report in Research and your agent links it and summarises it.
Run deep research on our roof replacement financing offer for homeowners in Charlotte, North Carolina, US.
Your agent uses start_offer_research for an offer, start_niche_research for a niche with no specific offer, and poll_offer_research to check progress.
What you can give the agent
Input | What it does |
Offer | What you sell, in plain words. Leave it out to research the niche. |
Niche | The market in plain words, for example "residential roofing". It seeds the keyword table and the ad search. |
Country (required) and city | The market the report covers. |
Your landing page | Read for product facts. |
Competitor domains | Up to five known competitors. |
Extra questions | Up to five questions the report must answer. |
Mode | Deep (the default, thorough) or Standard (cheaper and shallower). |
Reuse before you pay again
If your workspace already has a report for the same niche and market from the last 30 days, granvl returns that report instead of starting a new run. Your agent offers three paths: use it as it is, deepen part of it, or break out from it. It starts a fresh run only when you ask it to start over.
What a report contains
Every run, deep or standard, offer or niche, produces the same twelve sections. Citations such as [3] point to the numbered sources in section 12. Anything the research could not establish is marked as not established instead of being filled in.
# | Section | What it covers |
01 | Executive summary | The key takeaways. |
02 | Market snapshot | Buyer awareness and sophistication, how buyers find providers, seasonal timing and the questions buyers ask. |
03 | Keyword opportunity | Search demand and costs from Google Ads keyword data. |
04 | Competitors & offers | Competitor profiles (promise, mechanism, strength, what to watch), an offer comparison and an opening to test. |
05 | Paid ads & landing-page patterns | The common hook, first step and payoff, plus ads running for the niche and the pages they send to. |
06 | Audience & customer voice | Themes buyers care about, verbatim quotes with links to the source (Reddit, reviews, YouTube, forums) and a bank of their exact phrases. |
07 | Buyer journey | Stages, triggers and timeframes, and what buyers tried before. |
08 | Objections & credible responses | Each doubt with evidence, how competitors answer it and a suggested response. |
09 | Messaging angles | Angles worth testing, each with a hook, the belief to install and the proof needed. The title counts them, for example "Five messaging angles". |
10 | Claims & compliance notes | Claims to substantiate and rules to review. |
11 | Gaps & next steps | What the research could not settle, the next action for each, and where to start testing. |
12 | Sources & research provenance | Every source, numbered and grouped by category (customer voice, competitors, market context, compliance, research data, ad landing pages). |
After section 12, the report's Research library section lists every quote and source as evidence, numbered E001 onward.
The chips above the title show DEEP RESEARCH or STANDARD RESEARCH, the market, the snapshot date and the coverage level.
The keyword table
Up to 20 searches, sorted by monthly volume, with the columns Keyword, Intent, Searches / mo, CPC, Top-page bid and Comp.
The searches come from the phrases the research found buyers actually type, not only the topic you gave.
Searches with no buying intent (logins, certifications, training, jobs) are left out. The note under the table names a few of them.
Figures are in USD from Google Ads keyword data. CPCs of $40 or more are highlighted. Google groups close variants under identical figures, so equal rows don't add up.
If keyword data can't be pulled for your market, the section says so instead of showing figures.
Ads in the report
Section 05 shows up to six ads and up to three landing-page teardowns. Job and recruiting ads are skipped, and an ad has to contain a whole search phrase to count. Every ad the report pulls is also saved to Research > Ads. See Study competitor ads and landing pages.
Coverage and automatic deepening
Each report is measured against three floors: 10 verbatim customer quotes, 3 named competitors and 15 evidence sources (customer-voice or competitor sources). When a finished run comes in under the quote or competitor floor, granvl runs extra passes before the report is handed over: a customer-voice pass for quotes and a competitor pass for competitors. These passes are part of the estimate and are only charged when they run.
Chip | Meaning |
SOLID COVERAGE | All three floors are met. |
FAIR COVERAGE | A floor is missed, but the report has at least 5 quotes and 2 competitors. |
THIN COVERAGE | Fewer than 5 quotes or fewer than 2 competitors. |
Point at the chip to see the counts and which automatic passes ran. A fair or thin report is a good candidate for deepening.
Deepen a report in place
Deepening adds to an existing report without a new run. Ask your agent which parts to grow and it calls deepen_offer_research.
Ask for | Option | What it adds |
More customer quotes |
| Verbatim quotes with permalinks from Reddit, Trustpilot, Yelp and YouTube, added to customer voice. |
More competitors |
| New competitor profiles. |
More objections |
| New objections with evidence and a response. |
Compliance |
| New rules to review. |
Fresh keyword data |
| Re-pulls the keyword table. |
Fresh ads |
| Re-pulls the ad library and landing pages. |
New sources are numbered into the report and each pass saves a new version of the document. A section holds a limited number of items (customer voice holds 12 quotes). Anything past that limit is kept as linked evidence, and your agent tells you.
The quote and research passes are small, and your agent can cap them with a credit budget. Re-pulling keywords or ads is charged on its own (an ad re-pull with landing-page teardowns can run 30 to 40 credits), so your agent should confirm those with you first.
Deepen the Charlotte roofing report: more competitors and more objections.
Break out an offer or an angle
A breakout is a child report focused on one offer, or on one of the parent report's messaging angles. It reuses the parent's niche, market, keyword table and ads, so you don't pay for those again, and it runs in standard mode unless you ask for deep. The flow is the same: estimate, yes, run. Your agent uses start_breakout_research.
Break out the "Financing before the next storm" angle from the Charlotte roofing report.
For an angle breakout, the angle has to be one of the titles in the parent's messaging angles section.
On the parent report, a Breakouts card above section 01 lists each breakout with its Offer or Angle chip, status, date and an Open button.
A breakout shows an OFFER BREAKOUT or ANGLE BREAKOUT chip, and its breadcrumb runs Research, then the parent report, then the focus.
In the Research library, the parent shows how many breakouts it has. In list view, breakouts sit under their parent. In grid view, each breakout card says which report it breaks out from.
Read, share and export a report
Click Research in the sidebar. Reports carry a Report chip.
Open a report to read it.
Use the buttons at the top right:
Tags adds topic tags that filter the Research library.
Copy link copies the report's address for teammates.
Export downloads Markdown (.md) or Plain text (.txt).
Use as agent context hands a summary of the report to your agent with its strategy brief.
You can rename a report, but its content changes only through deepen passes. Reports your agent runs are filed under your workspace's default brand, so they show under All brands and under the default brand.
To read a report as a formatted web page, ask your agent to open it as HTML. get_research_document with format: "html" returns a self-contained page. Agents with a browser pane, such as Claude Code and Codex, can save it as a local file and open it there.
Open the Charlotte roofing report as an HTML page so I can read it.
Agent context
A niche or offer report is switched to Used as agent context when it is filed. Your agent then receives a summary of it with every strategy brief: the executive summary, the messaging angles, the objections, the customer language and the gaps, with a pointer to the full report. Breakouts are not switched on; your agent sees them listed under their parent instead. Click the button to turn either on or off. See Give your agent your strategy and context.
How credits are charged
The estimate is itemized: the research run, the keyword pull, the ad pull, the quick read and the automatic coverage passes. A breakout has no keyword or ad pull.
The quick read is charged when it runs.
The research run is charged when the report is filed. The keyword and ad pulls are charged when they run, and the coverage passes only if they run.
If a run fails, or is still running after three hours and is written off, the research run is not charged.
Each deepen pass is charged on its own.
Every result tells your agent the credits charged and your remaining balance.
Other research your agent can run
Tool | What it does |
| Answers one specific question with source URLs. Small, reported cost. |
| Keyword numbers only: monthly volume, CPC, competition and top-of-page bids for seed keywords, a landing page or up to three competitor domains. A few credits. |
| A full Google Search keyword plan, saved to the Research library. A few credits. |
| Files cited quotes as evidence rows in Research. Free. |
| Read what is already in Research. Free. |