Connect with MCP
MCP tool reference
Choose the narrowest registered read tool that answers your question, and see which tools make changes.
Start with project discovery, inspect available evidence, then ask for the concrete record or dataset you need. List tools are bounded; follow returned cursors instead of assuming the first page is complete.
Choose a reading path
| Your question | Start with |
|---|---|
| Which project can I analyze? | list_projects |
| What is known about this business? | get_project_business_context |
| Which project, Action or prompt mentions this? | search, then fetch |
| What did an AI audit observe? | read_visibility_overview, then read_visibility_results |
| Which sources were used? | read_visibility_sources |
| How do answers portray us and competitors? | read_perception |
| Do answers state our facts correctly? (pilot) | read_fact_checks |
| Which ads appear in ChatGPT answers? | read_ai_ads |
| Who cites one specific URL? | read_source_url |
| What should I work on next? | read_actions |
| How do cited competitor pages differ from mine? | read_content_differentiation |
| Which products do AI answers recommend? | read_ai_shelf |
| What did the website crawl find? | read_site_health, then read_site_pages |
| Can AI crawlers reach the site? | read_ai_crawlability |
| Which AI crawlers visited, per server logs? | read_crawl_logs |
| Which pages get AI traffic? | read_ai_traffic_pages, then read_ai_traffic_url |
| How many visits came from AI assistants? | read_ai_referrals |
| Which connected reports exist? | read_integration_status |
| What does a performance window show? | read_performance, then read_performance with a dimension |
| Which research dataset should I inspect? | read_search_intelligence, then read_search_dataset |
Interactive views
In clients that support MCP Apps, such as Claude and ChatGPT, three tools open an interactive CiteLadder view inside the conversation:
| Tool | Shows |
|---|---|
render_visibility |
An overview or sources for one audit, or trends over a window you name |
render_site_health |
The Site Health results of one crawl |
open_analytics |
The CiteLadder project picker |
Clients without MCP Apps ignore the view and use the read tools instead.
Prompt and resource
Clients that support MCP prompts list business_health_review, which starts a growth health review of one project. The resource template citeladder://projects/{project_id}/context returns the same project overview as get_project_business_context.
Make changes
A connection approved with Allow changes also lists change tools, marked Changes in the catalog below. create_topic, rename_topic, delete_topic, confirm_topics, update_prompt_text, add_competitor, remove_competitor, update_action_status and cancel_audit run when called. prepare_add_prompts, prepare_archive_prompts, prepare_launch_audit, prepare_schedule and prepare_declare_implemented return a preview and a confirmation token; nothing changes until the assistant calls confirm_change with that token after you agree.
To generate prompts, the assistant follows the Prompt Builder’s steps: it checks your business facts with get_project_business_context, proposes topics with preview_topics and saves the ones you agree to with confirm_topics, offers your search data with read_seed_queries, then runs generate_prompts once you agree to the run. Topic previews and generation spend AI credits. Generated prompts wait in Prompts for your review; only the ones you accept are tracked.
Read records and windows precisely
The search tool finds projects, active Actions and prompts by text and returns citeladder:// record references. Pass a returned reference to fetch to read that record. Arbitrary URLs, SQL and filesystem paths are not valid substitutes.
Keep the exact audit, dataset or date-window identity in your analysis. A query table and a page table do not automatically establish query-page evidence.
Paging and limits
List tools return a bounded page. Pass the returned cursor with the same selection to continue; a cursor does not carry over to a different selection.
A connection can make 120 tool calls a minute, and an account 600 across its connections. Past that, the tool returns an error with the time to retry.
Preserve missing-data states
An unavailable result is not zero. A partial result is not complete. If a tool cannot return the requested scope, ask for the available inventory and explain the limitation.
The catalog below describes registered tools, not a guarantee that every dataset exists for your project.
Registered tools
The reference below is generated from the backend catalog. Your connected client’s catalog determines which tools are available on its server. Tools marked “Changes” appear only for a connection approved with Allow changes. The assistant asks before each change, and prepare tools change nothing until you agree to their preview and it calls confirm_change.
Fetch a record
fetch
Read one full record (an answer, Action, prompt or page) by the citeladder:// id another read returned. Never construct an id.
Input schema
| Parameter | Description |
|---|---|
id | A citeladder:// id exactly as a read returned it. |
Get project overview
get_project_business_context
Read one overview of a project in a single call: its identity and markets (with the market ids other tools take), then a short summary per section: business profile with owned domains and tracked competitors, latest visibility, the top 10 Actions, active prompts, Site Health, AI crawler access, demand, search performance, AI referrals, crawler logs, connected data and keyword research. Use it first to orient yourself, then the matching read_* tool for depth or paging (each section is that tool's default read). Omit sections for all of them; pass a few to keep the response small. A section can be unavailable on its own, such as visibility with no completed run (no_completed_run) or with the latest run's results still being written (metrics_pending, try again later).
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
sections | The sections to read; omit for all. profile also returns owned domains and competitors. |
List projects
list_projects
List the projects this connection can read. Start here when no project is known: every other project tool needs the id it returns. Each project has its id, name, brand, website, industry, primary market and the workspace it belongs to. Projects come oldest first, 50 per page by default; pass next_cursor for more. An empty list means no workspace was approved for this connection. To find a project by name use search; for one project in depth use get_project_business_context.
Input schema
| Parameter | Description |
|---|---|
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Open CiteLadder
open_analytics
Show the user the CiteLadder project picker, in clients that display apps, so they can choose a project to view. Use list_projects to find projects yourself.
Parameters: None
Read Actions
read_actions
List the work CiteLadder recommends to improve visibility, highest priority first. Without a status filter it lists open and in-progress Actions; each item has its id, target (page, prompt or source), status, priority score, approach and link, and status_counts counts every status. Items come in pages; pass next_cursor for more. Pass action_id for one Action in full: its diagnosis, each finding with its remediation, the measured outcome and any declaration. Use update_action_status to dismiss or reopen one, and prepare_declare_implemented when its work is done.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
action_id | An Action id from a previous list, to read that one Action in full. |
status | Keep only Actions with this status.One of openin_progressimplementedmeasuringdonedismissed |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read ads in AI answers
read_ai_ads
Paid ads shown in ChatGPT Search answers for the latest or a chosen run: ad presence rate ("N of M ChatGPT answers"), advertisers with share and first/last seen, the ad share and best rank of the brand itself, text creatives (paged) and prompts that surface ads with competitor ads beside organic brand mentions. Only ChatGPT Search shows ads; other engines are not_applicable, never zero. Ads are paid placements: report them separately, never as citations, sources or a cause of visibility.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
audit_id | A run id (audit_id); omit for the latest run. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read AI crawler access
read_ai_crawlability
Read whether the site's robots.txt lets each AI crawler in, for the latest or a chosen crawl: whether robots.txt was fetched (and its status), the sitemaps it lists, and per crawler (such as GPTBot or ClaudeBot) its operator, purpose, the matching rule, root access and how many sampled URLs it may not fetch. This is permission, not observed visits: use read_crawl_logs for crawlers that actually came. unavailable no_site_crawl means no crawl exists; robots_not_observed means the crawl could not read robots.txt.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
crawl_id | A crawl id that read_site_health returned; omit for the latest crawl. |
Read AI referral traffic
read_ai_referrals
Visits that arrived from AI assistants such as ChatGPT, from GA4: sessions, share of all traffic, key events and top landing pages for a range. These are people clicking through; read_crawl_logs has crawler requests. An unavailable state means no referral data has been imported, which is not zero; read_integration_status says why.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
range | A preset window ending today; or pass start_date and end_date instead.One of 30d90d1y |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
Read the AI Shelf
read_ai_shelf
Read how AI answers recommend products for an ecommerce project: which products and merchants hold the "shelf" when buyers ask for a product category. Call it first with no target to get the catalog: categories with product counts, and up to 200 products with their category ids (products_omitted counts the rest). Then call it again with target_kind and target_id for one category or product: product visibility, share of shelf, average position, first-position win rate, the answer counts they rest on, when it was measured, and the holders (your products, competitors, merchants) with their best rank. unavailable no_product_catalog means the project has no product catalog, which is normal for non-ecommerce brands; use read_visibility_overview for brand mentions instead.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
target_kind | Pass together with target_id: whether it names a category or a product.One of categoryproduct |
target_id | A category or product id from the catalog this tool returns without a target; pass together with target_kind. |
Read AI traffic insights
read_ai_traffic_insights
Read the patterns CiteLadder found by joining AI crawler, referral and citation data for one saved window: pages crawled but never visited from AI, pages getting AI referrals but not crawled recently, crawler errors on valuable pages, and key events concentrated on few pages. Each pattern has a short explanation, the numbers behind it and the pages involved, with coverage. These are co-occurrence, not cause. It reads the newest saved 30-day window by default; custom dates must match a saved window exactly. unavailable means no insight snapshot exists yet, and coverage.notice says why, such as GA4 not being connected. Use read_ai_traffic_pages for the per-page numbers.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
range | A preset window ending today; or pass start_date and end_date instead.One of 30d90d1y |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
Read AI traffic by page
read_ai_traffic_pages
Rank the project's own pages by AI activity, to find which pages AI crawlers fetch, AI assistants send visitors to and AI answers cite. Each row is one page (URL, path, folder, resource class) with four measures, each carrying its own coverage: AI crawler requests (server logs), AI referral sessions and key events (GA4), citations in AI answers, and Site Health findings, plus its last crawl. The window defaults to the last 30d; rows come 10 per page (up to 100); pass next_cursor for more. observed_crawl_coverage says how complete the logs are, and a measure without a connected source is missing, not zero. Use read_ai_traffic_url for one page's timeline, read_crawl_logs for crawler-level detail, read_ai_referrals for site-wide referral totals, and read_site_pages for crawl data such as titles and scores.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
range | A preset window ending today; or pass start_date and end_date instead.One of 30d90d1y |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
folder | A site path prefix such as /blog/ to read only pages under it. |
resource_class | A resource_class a previous row returned, such as page, to read only that kind. |
verification | Keep only crawler requests whose claimed identity was verified, could not be verified, or failed verification.One of verifiedunverifiablefailed_verification |
sort | Row order by one measure, highest first, or by URL; omit for the default. Filters (folder, resource_class, verification) apply first.One of requests_descsessions_desckey_events_desccitations_descurl_asc |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read AI traffic for a URL
read_ai_traffic_url
Read the timeline of AI activity on one page of the project site, after read_ai_traffic_pages names it: the page's four measures (crawler requests, referral sessions, citations, Site Health findings) with their coverage and 4xx/5xx errors, then each crawler's first and last visit and request count, each AI source's first referral and sessions, and each citation by date and run. The window defaults to the last 30d. Each timeline is capped, and provenance.bounded is true when a cap was hit. The URL must be on the project's own site. unavailable url_not_joinable means the path cannot be matched (for example a redacted path); unavailable with no reason means no activity was recorded for that page in the window.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
url | A page URL on the project site, as read_ai_traffic_pages listed it. |
range | A preset window ending today; or pass start_date and end_date instead.One of 30d90d1y |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
Read content comparisons
read_content_differentiation
Read how the competitor pages AI answers cite differ from your own page on the topics they win. Use it before rewriting a page to compete. It returns up to the 10 newest comparison reports, each with its query, the owned page compared, the features both have (parity), those only competitors have (gaps) and those only you have, each with the share of inspected pages showing it. A report with state insufficient_evidence had fewer than 3 readable competitor pages or no matching owned page. An empty list means no comparison was made yet; this tool never reads new pages. Use read_visibility_sources to find the competing pages first.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Read AI crawler visits
read_crawl_logs
Read the AI crawler requests your server logs recorded, to see which crawlers actually visited, what they fetched and what they got back. View summary (the default) gives totals: requests, pages, active crawlers, error share and a daily series by purpose. View crawlers gives one row per crawler with status codes and verification. View coverage says how complete each day of logs is. View requests lists individual requests. The window defaults to the last 30d, except that requests without range or dates reads every retained day. The paged views return 10 rows by default (up to 100) with a top-level next_cursor; changing a filter needs a new first page, while a continuation may change limit. Failed-verification requests are left out unless verification asks for them. connection not_connected or missing coverage means unknown, not zero. Use read_ai_crawlability for robots permission and read_ai_traffic_pages for activity per page.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
view | summary is totals; crawlers is one row per AI crawler; coverage is how complete each day of logs is; requests lists individual requests, paged.One of summarycrawlerscoveragerequestsDefault"summary" |
range | A preset window ending today; or pass start_date and end_date instead.One of 30d90d1y |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
verification | Keep only crawler requests whose claimed identity was verified, could not be verified, or failed verification.One of verifiedunverifiablefailed_verification |
bot_id | A bot_id the crawlers view returned; keep only that crawler. |
status | An HTTP status code; keep only requests answered with it. |
folder | A site path prefix such as /blog/ to read only pages under it. |
resource_class | A resource_class a previous row returned, such as page, to read only that kind. |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read search demand
read_demand
Read the latest search-demand snapshot: the opportunities CiteLadder found in the project's own Search Console data for one window, such as queries in striking distance of page one, pages competing for the same query, click-through below the site's norm and rising or falling queries. It returns the window (pass it to read_query_evidence for the query rows behind it), the signal count by type, each detector's state, coverage (whether search data and query evidence were observed) and the change in signal count against the previous snapshot, which is not a cause. unavailable no_demand_snapshot means no snapshot was built yet, usually because Search Console is not connected or still importing; read_integration_status says which. The signals become Actions: use read_actions for the prioritized work. Keyword volumes from research live in read_search_intelligence.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Read fact checks
read_fact_checks
Read whether AI answers state the brand's facts correctly. Factual claims answers made about the brand in the latest or a chosen run are checked against the brand's confirmed facts. The summary view gives accuracy (supported out of supported plus contradicted) with its coverage, by topic and engine, the contradicted claims with the fact they contradict, and sources cited alongside them. The claims view lists every checked claim with its quote, verdict and the facts used, paged (50 by default, pass next_cursor). Use read_perception for tone rather than accuracy. Always state the coverage and quote the fact. accuracy_state not_enabled, no_facts, no_claims, pending or unavailable means there is no value, never zero; inconclusive and not_covered are not errors in the answer. Sources are cited alongside a contradiction, never its cause.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
audit_id | A run id (audit_id); omit for the latest run. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
view | summary is accuracy and its coverage; claims lists the checked claims, paged.One of summaryclaimsDefault"summary" |
topic | With view claims: keep only claims about this kind of fact.One of pricingplansintegrationsavailabilitymarketspoliciesspecscompany |
verdict | With view claims: keep only this verdict; contradicted finds the errors.One of supportedcontradictedinconclusivenot_covered |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read connected data
read_integration_status
Read which data sources (Search Console, GA4, server logs) are connected to the project and how far their import has got, to explain why a traffic or search read is unavailable. It returns the overall stage (not_connected, connected, importing, core_data_ready, analysis_ready or import_failed), the backfill state and the date data is imported through, whether performance and demand snapshots exist, and each connection with its provider, property and last sync. Read it when another read returns unavailable or not_connected, before reading that again. Connecting a source happens in CiteLadder, not through this tool.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Read page text
read_page_text
Read the words of one crawled page of the project's site, by URL or by site_url_id from read_site_pages: its title, meta description, h1-h3 headings, then the visible body text (up to 36000 characters in all; text_chars_omitted counts any body text left out), with its URL, page type and when it was fetched. Use it to quote, review or rewrite what a page actually says. It reads the latest crawl, or crawl_id; it never fetches the live page, so the copy is as of fetched_at. unavailable page_not_crawled means the crawl has no page at that address, and crawled_urls lists the nearest crawled addresses to try; no_site_crawl means no crawl exists.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
crawl_id | A crawl id that read_site_health returned; omit for the latest crawl. |
url | The page address, such as https://example.com/pricing; scheme, www and a trailing slash are ignored. |
site_url_id | A page id (site_url_id) from read_site_pages; pass this or url. |
Read answer perception
read_perception
Read how AI answers portray the brand and competitors in the latest or a chosen run: net sentiment (-100 to +100) per brand, engine, topic and prompt, each with its coverage; praise and criticism by theme; how often answers recommend or advise against the brand; and the sources cited alongside criticism. The summary view returns all of that; the quotes view lists the verified quotes behind it, paged (50 by default, pass next_cursor). The response is always available: read perception_state, where pending, unavailable or no_mentions means there is no value, never zero. Always state the coverage. Sources are cited alongside criticism, never its cause. Use read_fact_checks for whether answers are factually right, and read_visibility_overview for how often the brand is mentioned at all.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
audit_id | A run id (audit_id); omit for the latest run. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
view | summary is sentiment and themes per brand; quotes lists the verified quotes, paged.One of summaryquotesDefault"summary" |
entity | With view quotes: a brand exactly as the summary names it, to quote only it. |
theme | With view quotes: keep only quotes about this theme.One of pricingvaluequalityfeaturesease_of_usesupportreliabilityperformancesecurity_privacyintegrationsreputation_trustavailabilityshipping_deliveryreturns_policysustainabilityother |
polarity | With view quotes: keep only praise or only criticism.One of positivenegative |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read search performance
read_performance
Read the site's organic search performance from Search Console and GA4: clicks, impressions, CTR, average position, sessions and key events for a window, with a series over time and an optional comparison window. Without dimension it returns totals, the series, data coverage and how many rows each breakdown has; with dimension it returns one page of rows by query, page, country, device or day (10 by default, pass next_cursor for more). The range defaults to last_synced, all imported data; most custom windows have no saved snapshot and return performance_range_not_projected, so prefer the preset ranges. not_connected means no search source is connected, which is not zero; read_integration_status says why. Use read_query_evidence for queries matched to crawled pages, and read_ai_referrals for traffic from AI assistants.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
range | The reporting window.One of 3_months6_monthscustomdaylast_syncedmonthweek |
start_date | First day of a custom window, inclusive. |
end_date | Last day of a custom window, inclusive. |
granularity | The bucket size of the totals over time.One of daymonthweek |
compare | The window to compare against; custom needs the compare dates.One of customnonepreviousyear_over_year |
compare_start_date | First day of a custom comparison window, inclusive. |
compare_end_date | Last day of a custom comparison window, inclusive. |
dimension | Break the totals down by this dimension, paged.One of querypagecountrydevicesearch_appearancedaybing_querybing_page |
sort | With dimension: one of clicks, ctr, dimension_key, impressions, position; prefix - for descending, such as -clicks. |
cursor | The next_cursor a previous page returned. |
limit | With dimension: rows per page.One of 102550100 |
Read prompts
read_prompt_portfolio
List the prompts the project tracks, so you know what is measured before reading results or changing prompts. Each row has the prompt id, text, topic, intent, buyer stage, cohort (core prompts are scored; comparison prompts name a competitor and are reported separately), status and whether audits measure it now, plus its prompt set and topic_id. topics lists every project topic (id, name, description), including topics with no prompts yet; topics_truncated says the list is partial. Rows come oldest first, in pages; pass next_cursor for more. To find one prompt by its wording use search; to see what engines answered for a prompt use read_visibility_results with its prompt_id. Prompt ids feed update_prompt_text, prepare_archive_prompts and prepare_launch_audit.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_set_id | A prompt set id from an earlier row of this tool; omit for every set in the project. |
cohort | Keep only scored or only comparison prompts; combines with the other filters.One of corecomparison |
active_only | true keeps only prompts audits measure now; false (the default) also lists disabled and archived ones.Default false |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read queries by page
read_query_evidence
Read the Search Console queries that bring searchers to each site page, matched to pages CiteLadder crawled, for one saved window. Use it to see which queries a page ranks for, or which page answers a query; for totals and trends use read_performance, and for the search signals found in the same window use read_demand. The window must exactly match a saved one: read_demand returns it. Any other window returns unavailable exact_query_evidence_window_not_projected, which is not zero. Each row is one query, page and day: the query, the page Search Console reported, the crawled page it was matched to (site_url_id), how the match was made (resolution_outcome), and impressions, clicks and CTR. Rows come in pages; pass next_cursor for more. Country, device and search type are not broken out.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
window_start | First day of a saved window, inclusive: read_demand's window.start. |
window_end | Last day of the same saved window, inclusive: read_demand's window.end. |
query | One search query, matched exactly ignoring case and spacing, not a search. |
site_url_id | A page id (site_url_id) from read_site_pages or an earlier row; keep only its queries. |
resolution_outcome | Keep only queries whose page match was exact, resolved (for example through a redirect or canonical), ambiguous or unresolved. All filters combine.One of exactresolvedambiguousunresolved |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read a research dataset
read_search_dataset
Read the rows of one saved keyword or backlink research dataset, after read_search_intelligence has named it. Use it for keyword volumes, rankings, competitor keywords or referring domains; use read_search_intelligence to choose the dataset and read_query_evidence for the project's own Search Console queries. It returns the dataset (kind, target, market, saved row count) and a page of rows (50 by default; pass next_cursor for more, with the same sort), each with a citeladder:// id for fetch. Columns depend on the dataset kind. Referring-domain and page totals are provider aggregates, not individual links: never report them as a link list. Rows are as saved at research time and are never refreshed by this read.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
dataset_id | A dataset id from read_search_intelligence; a dataset of another project is refused. |
sort | The column to order by, which must exist for the dataset kind: one of backlinks, dataforseo_rank, difficulty, domain, etv, id, intent, keyword, owned_rank_group, rank_group, referring_main_domains, search_volume, url, backlinks_spam_score, broken_backlinks, broken_pages, cpc, organic_keywords, rank_absolute, referring_domains, referring_pages. Omit to order by row id. Rows with no value sort last. |
direction | asc (the default) or desc; desc with a volume or rank column puts the largest first.One of ascdescDefault"asc" |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read keyword and backlink research
read_search_intelligence
List the keyword, competitor and backlink research datasets saved for this project, and whether the research provider is connected. Each dataset has its id, kind, target domain, market (location and language), status and whether its totals are aggregates rather than individual links, plus the project's owned targets, tracked competitors and latest research run. It lists datasets only: pass a dataset id to read_search_dataset for its rows. unavailable with no datasets means no research was run yet; this tool never starts research, which happens in CiteLadder. For the project's own Search Console queries use read_query_evidence instead.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Read seed queries
read_seed_queries
List the searches a prompt generation run could ground its wording on, for each search data source the project has (search_console or search_intelligence): each query's id, text and topic. Only non-branded, question-like searches are listed; a seed steers wording and is never copied into a prompt. There is no volume or impression count: never present a query as AI prompt volume. unavailable no_search_data means no source is connected. Pass the source as seed_source and the kept query ids as seed_query_ids to generate_prompts.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Read Site Health
read_site_health
Read the Site Health summary of the latest crawl, or a chosen snapshot: the web fundamentals and AI-readiness scores with their measurement state, how many pages were selected and analyzed, and the top 10 issues, each with its rule_id, severity, description, remediation and how many pages it affects. unavailable no_site_snapshot means no crawl was analyzed yet; this tool never starts one. Use read_site_pages with a rule_id to list the affected pages, read_ai_crawlability for robots access, and render_site_health to show the user the interactive view.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
snapshot_id | A Site Health snapshot id, or the crawl id it was built from; omit for the latest crawl. |
Read internal links
read_site_links
Read the internal links of crawled pages: per page, inbound and outbound link counts (overall and in main content) and nofollow inbound links, click depth from the home page, a bounded sample of the pages linking to it and linked from it with their anchors, and anchor diagnostics. Use it to find orphaned or buried pages. Pass up to 10 site_url_ids from read_site_pages to read those pages in one call (with smaller neighbor samples and anchor diagnostics counted by kind); missing_site_url_ids lists any without link metrics in this crawl (for example a page that was not analyzed). Otherwise rows come in pages; pass next_cursor for more. unavailable no_site_crawl means no crawl exists. Use read_site_pages for page scores and issues.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
crawl_id | A crawl id that read_site_health returned; omit for the latest crawl. |
site_url_ids | Page ids (site_url_id) from read_site_pages; omit to page through every page. |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read site pages
read_site_pages
Pages from a crawl, paged: URL, title, page type, status, scores, issue count and the rule ids of each page's issues by finding class. Pass url to find a page by its address, rule_id (from read_site_health top_issues or an issue group) to list exactly the pages affected by that issue, each with rule_evidence: what that check found on that page (a site-level architecture issue is recorded once on the home page, and its rule_evidence names the affected pages); filter by page_kind or status to find pages by type or status. This returns metadata, not page copy: use read_page_text for a page's words. read_site_health gives the totals.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
crawl_id | A crawl id that read_site_health returned; omit for the latest crawl. |
url | A page address or part of one, such as https://example.com/pricing or /pricing; keeps pages whose URL contains it, ignoring scheme, www and a trailing slash. |
rule_id | A Site Health rule_id; returns only the pages with a current issue of it. |
page_kind | Keep only pages of this type.One of about_contactalternativearticlecase_study_reviewcategorycomparisondocseditorial_indexfaqguidehomepagehow_tolisticlelocalotherpricingproductservicetrust_policy |
status | Keep only pages in this state.One of not_selectednot_measuredpendingrunningcompletedpartially_completederrorblockedcancellederror_or_blocked |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read a cited page
read_source_url
Read one cited page in depth, after read_visibility_sources or an answer names it: how often it was retrieved and cited, when first and last seen, the engines and models that cite it, the prompts it is cited for (up to 50), the brands it names (up to 12, including whether yours is there), and what CiteLadder read on the page itself. Omit audit_id to cover every run in the market, not just the latest. The URL must match the cited URL exactly; unavailable url_not_cited_in_selection means it was not cited in that selection.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
url | A cited URL exactly as read_visibility_sources or an answer listed it. |
audit_id | A run id (audit_id); omit for every run. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
Read AI visibility
read_visibility_overview
Read the headline AI visibility of one run: how often answers mention the brand and cite its site, the visibility score, rankings of the brand against each competitor (mention rate, citation rate, share of voice, average position), a breakdown per engine, and the run's status and answer counts. It defaults to the latest completed run in the default market; pass baseline_id to compare two runs. Each market is measured separately: pass market_id for another market, and never pool markets. unavailable no_completed_run means no run has finished yet; unavailable metrics_pending means the latest run has finished but its results are still being written, so try again later rather than report that nothing was measured. Use read_visibility_trends for change over time, read_visibility_results for the answers themselves, and read_visibility_sources for what was cited.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
audit_id | A run id (audit_id); omit for the latest run. |
baseline_id | An earlier run id (audit_id) to compare audit_id against. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
Read AI answers
read_visibility_results
Read the answers engines gave in one run, to see exactly what an engine said for a prompt. Each answer has the prompt text, engine, model, repetition, whether web search was used, the brands mentioned (with first position) and every citation (URL, domain, whether it is your site or a competitor's), plus a citeladder:// id for fetch. audit_id is required: take it from read_visibility_overview. Answers come in pages; pass next_cursor for more. Only core prompts are included unless cohort is comparison or all. Filters (prompt_id, domain, url, engine) combine. Use read_visibility_overview for rates and read_visibility_sources for citation totals.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
audit_id | A run id (audit_id) that read_visibility_overview returned. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
prompt_id | A prompt id from read_prompt_portfolio; keep only its answers. |
domain | A domain such as example.com; keep only rows citing it. |
url | Keep only answers that cite this exact URL. |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read cited sources
read_visibility_sources
Rank the domains or pages AI answers cited in one run, to find the sources worth earning a place on. Each row has how many answers and prompts cited it, its citation share and rate, ownership (yours, a competitor's or third party) and category; page rows also list up to 3 brands named on the page and whether there is an Action for it. It defaults to the latest run; unavailable no_completed_run means none has finished. Rows come in pages; pass next_cursor for more. level domain lists publishers; level url, or passing domain, lists pages. Use read_source_url for one page in depth, and read_visibility_results for the answers that cite it.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
audit_id | A run id (audit_id); omit for the latest run. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
level | domain counts publishers (the default); url counts individual pages.One of domainurlDefault"domain" |
domain | A cited domain such as example.com; with level url, lists its pages. |
cursor | The next_cursor a previous page returned. |
limit | How many rows to return; omit for the default page size. |
Read visibility trends
read_visibility_trends
Read how visibility changed over an explicit window of at most 366 days, as points per run or per day, week or month. Each point has the visibility score, brand mention and citation rates, share of voice, competitor rankings, the model and whether web search was on, and a comparison_key. Points with different comparison keys were measured differently and are not comparable; gaps are missing runs, not zero. At most the newest 100 points are returned. unavailable no_measured_runs means no run fell in the window. Use read_visibility_overview for one run in depth, or with baseline_id to compare exactly two runs.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
market_id | A market id from get_project_business_context; omit for the default market. Markets are never pooled. |
from_at | Start of the window, with a UTC offset, such as 2026-09-01T00:00:00Z. |
to_at | End of the window, after from_at and at most 366 days later. |
engine | Read one engine only; omit for every engine.One of chatgpt_searchgemini_consumerchatgptgeminiclaudegoogle_ai_overview |
cohort | core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.One of corecomparisonallDefault"core" |
granularity | One point per run (the default), or per day, week or month.One of rundayweekmonthDefault"run" |
transport_model | Keep only runs answered by this model, as a previous point named it. |
retrieval_enabled | true keeps only runs with web search on; false only runs without it. |
Show Site Health
render_site_health
Show the user an interactive Site Health view (scores, coverage and top issues) for the latest or a chosen snapshot, in clients that display apps. To reason over the data yourself, use read_site_health.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
snapshot_id | A Site Health snapshot id, or the crawl id it was built from; omit for the latest crawl. |
Show AI visibility
render_visibility
Show the user an interactive visibility view, in clients that display apps: overview, trends over a window, or cited sources for one run. To reason over the numbers yourself, use read_visibility_overview, read_visibility_trends or read_visibility_sources.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
view | Which view to show; each other field says the views it applies to.One of overviewtrendssourcesDefault"overview" |
audit_id | Overview or sources: a run id (audit_id); omit for the latest run. |
snapshot_id | Site Health only: a snapshot id; omit for the latest crawl. |
engine | Show one engine only, such as chatgpt; omit for every engine. |
cohort | core is the scored prompts (the default); comparison is reported separately.One of corecomparisonallDefault"core" |
from_at | Trends only, required there: start of the window. |
to_at | Trends only, required there: end of the window. |
transport_model | Trends only: keep only runs answered by this model. |
retrieval_enabled | Trends only: true keeps runs with web search on, false runs without it. |
competitor | Overview or trends: a competitor exactly as the rankings name it, to highlight. |
level | Sources only: domain lists publishers (the default); url lists pages.One of domainurlDefault"domain" |
domain | Sources only: a cited domain such as example.com, to list its pages. |
cursor | Sources only: the next_cursor a previous page returned. |
limit | Sources only: rows per page.Default 50 |
Search
search
Find projects, active Actions and prompts by text when you do not know where a record is. Returns matching records with ids; pass one to fetch for the full record.
Input schema
| Parameter | Description |
|---|---|
query | Words to look for, such as a prompt or brand. |
project_id | Search one project only; omit to search every project. |
limit | How many matches to return.Default 10 |
Add a competitor
add_competitor
Changes
Track one more competitor, so visibility reads rank its mentions and citations in AI answers beside your brand. Runs at once; refused if the project already tracks that name or has reached its competitor limit. get_project_business_context lists the competitors tracked now.
Input schema
| Parameter | Description |
|---|---|
name | The brand name as buyers write it. |
aliases | Other names AI answers use for the brand, such as a short form or old name.Default [] |
domains | The brand's own domains, such as example.com, so its cited pages are attributed to it.Default [] |
project_id | A project id that list_projects returned. |
Cancel an audit
cancel_audit
Changes
Stop a queued or running audit, after the user agrees, such as one launched by mistake or on the wrong engines. Runs at once and cannot be undone; answers recorded so far are kept, and no further prompt runs are spent on it. To launch a corrected audit use prepare_launch_audit. Refused if the audit is not in this project or has already finished.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
audit_id | A queued or running audit id (audit_id) that read_visibility_overview or confirm_change returned. |
Confirm a prepared change
confirm_change
Changes
Make a change a prepare tool previewed. Call only after the user explicitly agreed to that preview in this conversation. A token works once, for ten minutes.
Input schema
| Parameter | Description |
|---|---|
confirmation_token | The confirmation_token the prepare tool returned, exactly as given. |
Confirm topics
confirm_topics
Changes
Save the topic plan the user agreed to after preview_topics, in one change: create the topics they kept or added (each with the offerings preview_topics listed for it, or none), rename and delete existing ones. A deleted topic's prompts stay tracked without a topic. Runs at once and returns the project's topics with their ids for generate_prompts; refused if a named topic is not in this project or two topics would share a name.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
create | Topics to create: name, and offerings as preview_topics listed them (the project's saved offerings).Default [] |
rename | Existing topics to rename: id from existing_topics, and the new name.Default [] |
delete | Ids of existing topics to delete.Default [] |
Create a topic
create_topic
Changes
Add a topic, a named group of tracked prompts (for example "Pricing" or "Integrations") that visibility is broken down by. Runs at once and returns the topic id; pass it as topic_id to prepare_add_prompts to file new prompts under it. Topic names are unique in a project, ignoring case.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
name | The topic name, unique in the project. |
description | What prompts under this topic ask about; optional. |
Delete a topic
delete_topic
Changes
Delete one topic by name, after the user agrees, when the grouping itself is no longer wanted. Its prompts are kept, still tracked, without a topic, and its subtopics become top-level; recorded answers are kept. Runs at once and cannot be undone. To fix only the name use rename_topic; to stop measuring the prompts use prepare_archive_prompts.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
name | The topic name, ignoring case. |
Generate prompts
generate_prompts
Changes
Run CiteLadder's prompt generator for the project, as the Prompt Builder's Generate step does, once the user agreed to the run. The suggestions are staged for review and never tracked: only the user's Accept in CiteLadder's Prompts review (review_url) activates them. Spends AI credits, so call it once per agreed run: choose a new run_key for each agreed run and resend the same run_key on a retry, which returns the staged result instead of running again. distribution sets the branded and competitor-alternative shares, intent mix and personas; seed_source and seed_query_ids come from read_seed_queries; run_context is a note for this run only. A shortfall is reported with its reasons, never filled.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_set_id | A prompt set id from read_prompt_portfolio; omit when the project has only one prompt set. |
run_key | A key you choose once for this agreed run, such as a new random UUID. Resend it unchanged on a retry; a new run needs a new key. |
count | How many suggestions to stage; omit for the default.Default 10 |
topic_ids | Topic ids from confirm_topics or read_prompt_portfolio to cover; omit for every topic.Default [] |
run_context | A short note for this run only, such as a season or offering to focus on; never saved as a business fact. |
distribution | Shares of the run (0–1): branded_share names the brand, comparison_share asks for alternatives to a competitor, the rest is unbranded. intent_mix weights informational, commercial and transactional questions; personas are buyers to balance across. Omit for an unbranded run. |
seed_source | The search data that may steer wording: search_console, search_intelligence or none; omit to read every source. |
seed_query_ids | The read_seed_queries ids the user kept for that source; omit for all of them.Default [] |
Prepare to add prompts
prepare_add_prompts
Changes
Preview adding 1–50 prompts to a prompt set: which can be added, which are dropped and why, and prompt slots after. Nothing changes until the user agrees and you call confirm_change; confirmed prompts are measured from the next audit.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_set_id | A prompt set id from read_prompt_portfolio; omit when the project has only one prompt set. |
prompts | The prompts to add, each a short buyer question. |
Prepare to archive prompts
prepare_archive_prompts
Changes
Preview archiving tracked prompts so future audits stop measuring them; past results stay. Nothing changes until the user agrees and you call confirm_change.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_ids | Prompt ids from read_prompt_portfolio. |
Prepare to declare an Action implemented
prepare_declare_implemented
Changes
Preview declaring that the work of an open Action is done, so CiteLadder checks later evidence against it. Nothing changes until the user agrees and you call confirm_change.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
action_id | An open Action id from read_actions. |
declared_implemented_at | When the work went live; omit for now. Evidence after it is checked. |
Prepare to launch an audit
prepare_launch_audit
Changes
Preview launching an audit of a prompt set (or chosen prompts) on the given engines, with the prompt runs it can spend and its maximum provider attempts. Pass market_ids (from the project context; null is the default market) to run one audit per market. Pass max_attempts to cap the attempts. Nothing runs until the user agrees and you call confirm_change.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_set_id | A prompt set id from read_prompt_portfolio; omit when the project has only one prompt set. |
prompt_ids | Prompt ids from read_prompt_portfolio to audit only those; omit for every active prompt in the set. |
engines | The AI engines to ask; at least one. |
repetitions | How many times each prompt is asked per engine; omit for the project default. |
market_ids | Market ids from get_project_business_context; null is the default market. Omit for the default market only. |
max_attempts | The most provider attempts the user accepts; omit to use the estimate. The launch is refused if it needs more. |
Prepare an audit schedule
prepare_schedule
Changes
Preview a recurring audit schedule for a prompt set. Pass market_ids (from the project context; null is the default market) to run one audit per market. Each recorded answer spends one prompt run. Nothing changes until the user agrees and you call confirm_change.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_set_id | A prompt set id from read_prompt_portfolio; omit when the project has only one prompt set. |
cadence | How often the audit runs.One of one_timeevery_n_minuteshourlydailyweekly |
engines | The AI engines to ask; at least one. |
timezone | An IANA timezone such as Europe/London; omit for the default. |
repetitions | How many times each prompt is asked per engine; omit for the project default. |
interval_minutes | Minutes between runs; only for cadence every_n_minutes. |
next_run_at | When the first run starts; omit to start right away. |
market_ids | Market ids from get_project_business_context; null is the default market. Omit for the default market only. |
Preview topics
preview_topics
Changes
Propose buyer-facing topics for the project beside the topics it already has, as the Prompt Builder's topic step does. A topic is a category a buyer asks about (for example "golf nets"), never a product line, model, size or the brand. Spends one AI model call and saves nothing: show the user the existing and proposed topic names, let them keep, rename, delete or add, then save the plan they agreed to with confirm_topics. more lists proposals past the cap. Refused until the project lists at least one offering.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
Stop tracking a competitor
remove_competitor
Changes
Stop tracking one competitor by name, as get_project_business_context lists it, so visibility reads no longer rank it. Recorded answers are kept. Runs at once and cannot be undone; add_competitor tracks it again but its aliases and domains must be given again.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
name | The tracked competitor name, ignoring case. |
Rename a topic
rename_topic
Changes
Rename one topic, after the user agrees. Its prompts and past results stay under it, so prefer this to delete_topic and create_topic when only the name is wrong. Runs at once and returns the new name; refused if another topic in the project already has the name, or if topic_id is not in this project.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
topic_id | A topic id from read_prompt_portfolio topics or create_topic. |
name | The new name, unique in the project. |
Update an Action status
update_action_status
Changes
Dismiss one Action the user does not want to act on, or reopen a dismissed one. Runs at once. To record that the work was done, use prepare_declare_implemented instead.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
action_id | An Action id from read_actions. |
status | dismissed hides the Action from the open list; open restores it.One of dismissedopen |
Edit a prompt
update_prompt_text
Changes
Replace the wording of one tracked prompt, after the user agrees, such as to fix a typo or make it read like a buyer's question. Runs at once and returns the new wording; earlier measurements keep the old wording, so results before and after the edit may not compare. To stop measuring a prompt use prepare_archive_prompts, and to add new ones prepare_add_prompts. Refused if prompt_id is not in this project.
Input schema
| Parameter | Description |
|---|---|
project_id | A project id that list_projects returned. |
prompt_id | A prompt id from read_prompt_portfolio. |
text | The new wording: a short question a buyer would ask an AI assistant. |