project_id, which an agent gets from list_projects.
Every tool carries MCP annotations describing what it does, so a well-behaved client can prompt for confirmation selectively rather than on every call:
Tools marked write below change your account; quota means the call spends plan allowance. The protocol has no notion of cost, so billable tools are ordinary writes with the cost stated in their description — which is the only defence against an agent looping over a keyword list with a billable tool.
Onboarding
Start here.
list_projects gives the agent the project_id nearly everything else needs. create_project takes a name, a domain and at least one keyword, and starts the project’s first collection straight away — which spends at least five research lookups, one AI brand audit, and up to 101 site audit pages — a crawl of up to 100 pages and a web vitals check. If the keywords would take the organization past its tracked-keyword allowance, the call is refused before anything is created. get_usage_summary returns the same summary as the Usage section of Billing: the active plan, when the monthly allowances reset, and each allowance’s used, limit and remaining.
Seven tools are annotated destructive: delete_project, remove_competitor, remove_tracked_keywords, remove_geo_topics, remove_local_location, remove_local_keywords and delete_saved_keywords. Everything delete_project removes cascades and cannot be recovered.
Rank tracking
get_competitor_comparison is paged by keyword — page, per_page (default 25) and search.
Tags are worth knowing about — create_tag, list_tags, and assign_tags let an agent group keywords in ways the dashboard doesn’t surface as prominently.
add_tracked_keywords takes any place and language its engine searches from — google, bing, yahoo, baidu, naver or seznam. find_location finds a location code by name (austin, 10001), down to a city or postal code, and list_search_languages lists an engine’s language codes. Naver takes neither.
create_project takes a market for each service: tracking (location_code, language_code, search_engine), research (research_location_code, research_language_code) and AI visibility (ai_location_code, ai_language_code). One left out is the tracking market when that service takes it, and refused, naming the fields, when it doesn’t — list_search_languages with for: research or for: ai_visibility gives the valid ones.
A tracked keyword can’t be edited: update_tracked_keyword only pauses or resumes it. The same keyword can be tracked in several markets — location, language or search engine — as separate keywords, each with its own history, so to move one to another market, add it again with add_tracked_keywords.
get_ai_overview_summary describes the newest check — how many keywords have an AI Overview and how many cite your domain — with as_of giving its date.
Keywords
Backlinks
get_referring_domains, get_backlinks_list, get_anchor_texts, get_new_lost_backlinks and get_backlink_gap_result return one page at a time — page, per_page (default 25, up to 100) and an optional search — with the total, so an agent reads the first page and asks for more only if it needs them. For every individual backlink at once, use export_backlinks_csv; it exports the backlinks list only. get_backlink_gap answers with the first 25 referring domains of the gap it ran, and the total.
Audits
get_duplicate_content and get_broken_resources are dedicated tools that correspond to tabs in the audit detail view. Both are paged like the backlink lists — page, per_page (default 25, up to 100) and search — and return the total.
AI search
GEO
get_ai_visibility_overview returns the summary the GEO page shows — average mentions and citation rate across your prompts, and the daily trend over days (default 30) — rather than raw snapshots. Start there, then drill into a prompt with get_geo_topic_detail: each day’s mentions and citation rate, and the newest snapshot’s sources and every engine’s answer. Older snapshots carry their numbers only.
get_llm_response_for_keyword queues a fresh snapshot of one prompt: all six AI engines — ChatGPT, Claude, Gemini, Perplexity, Google AI Overview and Google AI Mode — are asked, and each answer is stored. It returns a job status, not the answer; read the result with get_geo_topic_detail. Its platform argument is accepted for compatibility and ignored.
Domains and tech stack
Each is a live lookup and spends one research lookup, unless Surnex already has a cached answer. All five work on any domain, not only your own. They’re billed to the organization, not a project: each takes an optional
organization, needed only if you’re in more than one. They work even when your only project is the sample.
Competitors
Local SEO
Local SEO starts from a location: the business’s Google listing plus a grid of Maps searches around it. The order is:
search_local_listings— find the listing by business name and townadd_local_location— add it with agrid_sizeof 3, 5 or 7 points a side and aspacing_kmbetween themadd_local_keywords— up to 10 keywords at thelocation_id; the first check is queued straight away and lands in a few minutesget_local_grid— one keyword’s position at every grid point, the top 3 at each, and every check’s summary
null means the business isn’t in the top 20 at that point. get_local_rankings is the Maps pack at each location’s centre, from the latest check unless latest_only is false.
To change a location’s grid or listing, use update_local_location; spacing_km is 0.5, 1, 2 or 5. update_local_keyword pauses or resumes one keyword and keeps its history; remove_local_keywords deletes keywords and their history to free room at the location.
Web vitals
Trends
Common arguments
organization — optional on org-scoped tools, taking a name or an id. Resolved automatically when you belong to exactly one organization. With several and none named, the call is refused and the error lists them; the server doesn’t guess. See choosing an organization.
project_id — required by most tools, obtained from list_projects. A project you can’t access returns “not found” rather than “not yours”, so a not-found isn’t proof of deletion.
Locale — project tools start on the project’s own market for that service when location_code and language_code are left out: add_tracked_keywords and search_local_listings on its rank tracking market, add_geo_topics and the AI searches on its AI visibility market, AI keyword trends on its research market. Research, trends and domain lookups default to location 2840 (United States) and language en — for another market there, tell the agent explicitly. Backlink tools take no location.
Your role applies
The OAuth token acts as you, so a tool can only do what your role permits.create_project and delete_project need an admin or owner, exactly as in the dashboard; a member’s connection is refused both.
No token can mint an API key, change billing, invite or remove people, or reach an organization you’re not a member of — regardless of role.
Related
- MCP playbooks — prompts that use these well
- MCP authentication — the OAuth flow and what a session permits
- Usage and limits — the quota these draw on