Keyword research with an AI agent

Before buying any data, read your own. With Search Console connected to the project, get_striking_distance returns the queries where your site already ranks in positions 5 to 20, with the page ranking for each. Those pages are close to page-one traffic. They usually need a better title, a clearer answer, or a section on the subtopic people are searching for, rather than a new page.

Using my Search Console data for example.com, list the queries where I rank between positions 5 and 20, grouped by the page that ranks. For the five pages with the most impressions, suggest one change each.

get_search_console_performance adds the wider picture: clicks, impressions, click-through rate and average position by query and by page, against the previous period. Queries with plenty of impressions and few clicks point at the title and description. The free SERP simulator shows how a rewritten title and description fit in a Google result before you ship them.

Both tools read your own data and cost no credits. They also hand you seed topics for the next step: the themes where Google already sees your site as relevant.

Keyword research goes wrong when the agent doesn't know the business. "Invoice template" has plenty of volume, but if you sell accounting software to agencies, most people searching it will never buy. get_project_context gives the agent what the business does, who the customer is and the current goal. If those sections are empty, fill them before any paid research.

Read the project context for example.com. Before any keyword research, tell me in two sentences who we sell to and what they search for before they know our name. Ask me if the context doesn't say.

Difficulty only means something next to your site's strength. get_domain_overview returns your domain's estimated organic traffic, the number of keywords it ranks for and how those rankings spread across positions. A site that ranks for a few dozen keywords has little reason to chase terms with a difficulty of 70. Pass a competitor's domain to see theirs.

get_ranked_keywords goes one level deeper: the keywords a domain ranks for, 100 per call by default and up to 1,000, with the position, volume and ranking URL of each. On a competitor, it is a ready-made seed list. On your own site, it is the third-party view of what Search Console measures, and it maps keywords to the pages that already hold them.

Both cost credits, and both are estimates built from third-party data.

research_keywords takes one to five seed keywords and returns related keywords with monthly search volume, keyword difficulty from 0 to 100, CPC in US dollars, paid competition and search intent. It costs roughly 30 to 100 credits per seed, depending on the data source. The metrics are also written to the project's cache, so the saved list shows them later without buying them again.

For example.com, research keywords from these seeds: [seed 1], [seed 2], [seed 3]. Drop anything with difficulty above 30, volume under 50, or no connection to what we sell. Group the rest by intent and show me the top 25 by volume. Don't save anything yet.

A few things to know about the numbers:

• They are estimates. Volume is a monthly average from third-party data, difficulty is a model's score, and neither measures anyone's traffic.
• Google Ads data groups close variants, such as plurals and misspellings, under one volume. includeClickstreamData: true splits them using clickstream data and doubles the credit cost. It is worth it for a final shortlist, rarely for a first pass.
• In countries whose data comes from Google Ads rather than a clickstream source, difficulty and intent come back empty and clickstream data has no effect. Filter on volume and CPC there instead.
• A call returns up to 100 rows by default. limit raises that to 500.

To score a list you already have, such as a competitor's keywords or phrases from customer calls, use get_keyword_metrics. It looks up exact terms with no expansion, up to 700 per call, and names the terms it found no data for instead of silently dropping them.

To see what this data looks like before connecting anything, the free keyword generator runs one topic in one country with no account.

Most of an expanded list isn't worth writing for. Have the agent cut on three grounds, in this order: wrong for the business, too difficult for the site, and already covered by a page you have.

Then group what's left so that each group could be answered by one page. A comparison and a how-to on the same topic need different pages. Each group should end up mapped to one existing URL or to one page you'll write.

Take the keywords that survived. Group them so each group could be answered by one page. For each group, name the primary keyword, and say whether a page on example.com already ranks for it (check Search Console first, which is free) or whether it needs a new page.

IndexZero doesn't return the results page for these queries. If the agent describes what currently ranks, that came from its own web search, so ask it to say so. The keyword clustering workflow in the agent skills pack gives it a fuller procedure for this step.

find_serp_competitors takes up to 200 keywords and returns the domains that rank alongside you most often, with how many of the keywords each one shares and its average position. It often surfaces publishers and marketplaces you would never call competitors. They still take the clicks, so they belong in the plan.

Using the keywords I've saved for example.com, find the domains that rank alongside me most often. Separate direct competitors from publishers and marketplaces, then show me the top pages of the two closest direct competitors.

Behind that prompt the agent calls list_saved_keywords, find_serp_competitors and get_domain_top_pages. The last two cost credits. The competitor's top pages show which topics bring them traffic, and the topics you don't cover yet are candidates for the next round of seeds.

save_keywords adds keywords to the project's saved list. It is free, makes no provider call, and ignores duplicates in the same market, so running it twice does no harm. list_saved_keywords reads the list back with its cached metrics and can filter by text. Tags are added in the dashboard.

Save what you'll write for or track, not everything the research returned. The saved list is what the next steps read: a rank tracker built from it, or next month's check of which pages moved.

Save the primary keyword and the two strongest secondary keywords from each group we agreed on. Then log this research in the project context so we don't buy it again, and save a one-page report listing the groups and the page each one maps to.

From here, rank tracking with an AI agent turns the saved list into positions you can watch. The wider method, including cost control and checking the agent's answers, is in SEO with AI agents.