Build a Weekly AI Visibility Report an Agent Writes for You
A concrete weekly loop where an agent reads live visibility data, writes the report, and ships it through the Promptwatch createReport tool.
A weekly visibility report is the kind of work that should not need a person to write it. The data already exists. The prompts are tracked, the citations are collected, the crawler logs are streaming, and the visitor analytics are attributing traffic. What usually happens is that someone opens four tabs on Monday morning, copies numbers into a doc, writes a paragraph of interpretation, and sends it to the team. That is exactly the job an agent should own.
This guide builds a weekly AI visibility report loop that an agent writes for you. The agent reads live data through the Promptwatch MCP server, drafts the sections a person would write, and ships the report through the createReport tool. The human job shrinks to reading the result and forwarding it.
What the report should actually contain
Before wiring the agent, decide what a useful weekly report looks like. A good one answers four questions. Did visibility move this week, and where. Who got cited instead of us. Did AI crawlers reach the pages we care about. Did any of that turn into traffic. A bad report lists numbers without interpretation, which is what a dashboard already does.
The report has five sections. A headline summary of the week, a prompt-by-prompt visibility change, a citation shift section, a crawler and traffic section, and a prioritized list of next actions. Each section should be short. The value is in the interpretation, not the row count.
The tools the agent will use
The agent works through the Promptwatch MCP server at https://server.promptwatch.com/mcp. The read tools do the heavy lifting. listPrompts gets the tracked set. getVisibilityTimeSeries finds the prompts that moved. getPrompt reads the current answer for a prompt that dropped. getCitations and getCitationTopPages show who is being cited and for what pages. getCompetitorHeatmap shows whether a loss is yours alone or a category shift. listRedditCitations and listYoutubeCitations cover the off-domain channels that often explain a visibility swing.
The crawler and traffic side uses getCrawlerTrend, getTopCrawlerPages, getVisitorTrend, getVisitorTopPages, and getVisitorTopSources. Together those let the agent connect a crawl event to a citation to a traffic result. getResponseSentimentTimeSeries adds sentiment context where it matters. listActionItems reads the action board so the report can reference work that is already queued instead of inventing new tasks. The single write tool the loop needs is createReport, which builds the report from the live data the agent just read.
The loop, step by step
Start the session with a read-only key. The agent should not be able to publish or mutate anything during a report run. The loop is read, interpret, and write one report.
Step one is the headline. The agent calls listPrompts and then getVisibilityTimeSeries for each tracked prompt, and identifies the three that moved most in the last seven days. It writes a two-sentence summary. One sentence for the direction, one for the magnitude and the prompt. If nothing moved, the report says so. A week with no change is a valid result and the agent should be allowed to return it.
Step two is the prompt-by-prompt detail. For each prompt that moved, the agent calls getPrompt to read the current answer and getCitations with getCitationTopPages to see who took the citation. It writes a short paragraph per prompt that names the competitor, the page they were cited for, and whether the loss appears in getCompetitorHeatmap as a category shift or a prompt-specific swap. listQueryFanouts can reveal whether the real query shifted, which often explains a drop that looks unexplained.
Step three is the citation shift section. The agent pulls listRedditCitations and listYoutubeCitations to flag any new off-domain citations, since a new Reddit thread or YouTube transcript citing the brand can offset a loss on the main answer. It notes any new citation domains and any domains that dropped off.
Step four is the crawler and traffic section. The agent calls getCrawlerTrend and getTopCrawlerPages to report which pages AI crawlers read most this week, and whether crawl behavior changed. It calls getVisitorTrend, getVisitorTopPages, and getVisitorTopSources to report the AI-referred traffic that followed. The goal is to connect the dots. A crawler hit this page, the page got cited for this prompt, and this much traffic came through. Where the chain breaks, the report says so.
Step five is the next-actions list. The agent calls listActionItems to read the action board and surfaces the three highest-priority open items, with the reasoning from the diagnosis above. It does not create new actions during a report run. Creating actions is a separate loop with a write key, and mixing the two is how reports start to mutate state by accident.
Shipping the report
With the five sections drafted, the agent calls createReport to build the report from the live data. That is the one write call in the loop, and it is safe because a report is a document, not a change to the site. The report lands in Promptwatch, where the team can read it, share it, or pull it into Looker Studio through the existing integration.
If you want the report outside Promptwatch, the agent can also write the drafted sections to a markdown file in your repo, which is a read-only action against your filesystem and does not need the write key. The createReport call is still the canonical version, because it is built from the same live data the agent just read, with no copy-paste step in between.
Adding context from published research
A weekly report is more useful when it sits against category context. The Promptwatch data pages publish research you can cite directly. The average-sources-per-response report at https://promptwatch.com/data/average-sources-per-response?ref=101seomedia tracks how many sources AI answers cite on average, which is the baseline your citation count should be compared against. The chatgpt-ads-over-time report at https://promptwatch.com/data/chatgpt-ads-over-time?ref=101seomedia tracks ad frequency by prompt type over 90 days, which is the context for any ad-driven visibility change. The agent can reference these in the report header so the team knows what normal looks like, instead of reading your numbers in a vacuum.
Cite the report and the date. Do not paraphrase a number from memory. If the published research says sources per response is trending a certain way, link the report and let the reader open it.
Keeping the loop honest
A few rules keep this loop from drifting into fiction. The agent should quote numbers it just read, not numbers it remembers. If a tool returns no data for a section, the section says no data this week, not a plausible sentence. The agent should not invent competitor names that did not appear in getCompetitorHeatmap or getCitations. And the next-actions list should reference the action board, not generate fresh tasks mid-report.
Run the loop read-only first for a few weeks before you trust it. Read the report the agent writes, compare it to the dashboard, and fix the places where the interpretation is wrong. Once the report is reliable, schedule it. The loop ends in createReport, and your Monday morning opens with a report that is already written.