The data-backed path: a research run, ranked clusters, a content plan
The data-backed path starts from search data instead of from an idea. A research run maps the niche, the opportunities rank what to write, and the content plan turns the best of them into briefs. It needs a paid plan.
What a research run does
start_research_run discovers keywords for the niche, reads who ranks for them, evaluates those competitors and groups the keywords into opportunity clusters. Each run spends one research credit, and your agent asks you before it starts one. On the free plan the call returns a structured wall instead of a run.
The call returns a runId. Over MCP it can start at most once a minute, a guard against an agent looping on your credits.
Waiting for it
A run takes about an hour. Your agent tells you that, then polls get_research_status once every 30 to 60 seconds at most. Each poll returns a small fixed shape: status, the current phase, percentComplete and elapsedSeconds.
A failed run carries a failure object with a failureClass and a retryable flag. true means a passing upstream problem and a retry is safe. false means a retry will fail the same way. A run still in the initializing phase after a long time is stalled, not queued, and your agent reports it.
In the web app, the project overview shows the same run as a four-step progress bar (Discover, SERP, Profile, Cluster) and says to expect about an hour.
Reading the opportunities
list_opportunities returns clusters ranked by opportunity score, from 0 to 100 against the highest-scoring visible cluster. Four goal filters narrow the list without changing any score:
| Goal | A cluster qualifies when |
|---|---|
fast_wins | a keyword has an average or high volume band and difficulty ≤ 40 |
high_intent | a keyword is commercial or transactional |
authority_building | it has informational keywords and no commercial or transactional |
competitor_gap | it is a gap and a competitor you marked important ranks top 10 |
Coverage decides what you see by default. Clusters that are a gap or partial show; clusters your site already covered stay hidden unless the agent asks for them, as refresh candidates. A cluster your product cannot serve carries a fitFlag with a plain reason and is scored down, not hidden.
get_opportunity_detail opens one cluster: its top 20 keywords, the top 10 ranked pages, a podium of the top 5 competitors, linked suggestions and the un-normalized rawOpportunityScore.
Shaping the list
Three levers change the ranking, and each one moves the 0 to 100 scale for every other cluster:
set_opportunity_statuswithdismissedhides one cluster from the list and from the plan harvest;defaultbrings it back. A dismissal lasts until the next run rewrites the clusters.set_excluded_termsnames what you do not sell, up to 30 terms. Keywords mentioning them are scored down and left out of the harvest. The call replaces the whole list, and the list survives new runs.set_competitor_importanceis the one competitor lever.importantboosts clusters where that competitor ranks top 10 by 1.25x;ignoreddrops it from the competitor surfaces and the rankings.
From opportunities to a content plan
create_content_plan_from_opportunities harvests the top 30 clusters into article suggestions, one per cluster. It skips dismissed clusters, fit-flagged clusters, excluded keywords and clusters your site already covers at 80% or more. Calling it again reuses the plan and skips clusters that already have a suggestion. Because it can add up to 30 suggestions at once, your agent confirms with you first.
To pick clusters one at a time instead, use the web app's Forge brief button on a cluster, which links the suggestion to that cluster. Over MCP, the nearest call is add_article_suggestion with the cluster's title; it creates a suggestion from the title alone, without the cluster link.
Either way, briefs forge on their own. Each suggestion lands in generating_brief, and download_brief_markdown returns its brief once it reports brief_ready. No generate_article_brief call is needed.
What you see in the web app
The Opportunities screen shows every cluster as cards or a table, with the goal filters, a coverage dropdown, sub-niche tabs and a gold star on the strongest picks. Each cluster not yet in the plan has Forge brief and a Dismiss button with an undo.
The Content Plan screen is a board with one column per status, up to published. Next comes drafting and verification.
Markdown version of this page, for your agent.