Tools Reference

The Echod MCP server exposes 22 read-only tools. Your AI assistant calls them automatically based on your questions - you never invoke them directly, but this reference helps you understand what is available and what the numbers mean. Every tool is scoped to the projects your token can open. Tools that read analytics accept a reporting window of up to the last 90 days and, where it makes sense, a platform or region filter matching what your project tracks.

​

Shared parameters

Most analytics tools accept the same window and scope parameters. They are listed once here and referenced below.

​

Window parameters

Every response states the resolved window it answered for, so the assistant never has to guess what “30d” meant on the day it asked.

​

Paging parameters

List responses carry total, page, pageSize and hasNext, so the assistant can tell whether to paginate.

---

​

echod_list_projects

Lists the Echod projects your account can access, across every organization you belong to. This is always called first: every other tool needs a project id from here. Each project tracks one brand on one website in one language. Returns: the projects with their id, name, website, language, status and organization. isCovered: false means the organization’s plan no longer funds the project, so its data has stopped moving.

---

​

echod_get_project

The project’s configuration: the own brand and website, language, status and crawl schedule, the researched brand profile, the tracked competitors, and the regions and platforms with whether each is enabled and covered by the plan. Returns: the full project settings. The assistant uses this to learn which platform and region values the analytics tools accept for this project.

---

​

echod_get_crawl_status

Whether the project is being crawled right now, when the last crawl completed, when the next is due, and how large it is. The assistant calls it when analytics come back empty or stale. Returns: the crawl state. isFirstCrawlPending means no data has been published yet; isPublishPending means the latest run has finished but its numbers are not visible yet; state pausedNoPlan means the plan does not cover the project.

---

​

echod_get_dashboard

The project overview for a window - the natural starting point for “how are we doing” questions. Also accepts the window parameters. Returns: the own brand’s and tracked competitors’ visibility over time, the score breakdown (average position, share of voice, own-site citation rate and sentiment, each with its delta against the preceding equal-length window), visibility per platform, the top topics, the competitor ranking and the recent changes feed. lastCrawledAt null means no crawl landed in the window.

---

​

echod_get_brand_report

A per-brand metric table for the own brand and its tracked competitors - for “who beats us”, “compare us to X across platforms” and “where do competitors own topics” questions. Also accepts the window parameters. Returns: one or more groups, each with a per-brand table: visibility, share of voice, average position and sentiment, each with its delta against the preceding equal-length window, and isNewEntrant for a brand that was absent before. A competitor the crawl has never named is listed at zero rather than dropped.

---

​

echod_list_topics

The project’s topics with the own brand’s metrics per topic for the window. The per-platform states make the list a ready-made topic-by-platform heatmap. Also accepts the window and paging parameters. Returns: topic rows with score, visibility, share of voice, average position, sentiment, trend against the preceding window, prompt count, and platformStates: one entry per platform with its label, the own brand’s visibility there and a state (high 66 and above, medium 33 to 65, low below 33, none when that platform has no answers for the topic in the window). stats summarises the whole set.

---

​

echod_get_topic

One topic in depth - for “how do we compare to competitors on topic X”. Also accepts the window parameters. Returns: the topic’s metrics, the own brand’s visibility over time, the per-brand visibility and position series, the share-of-voice split (with an Others slice when brands nobody tracks hold a share), each brand’s sentiment, the per-brand table (topBrands) and the domains AI engines retrieved most for this topic (topDomains, with each domain’s hash for echod_get_citation_domain).

---

​

echod_list_prompts

The tracked prompts - the questions Echod asks each AI platform - with the own brand’s visibility and average position per prompt for the window. Also accepts the window and paging parameters. Returns: prompt rows with visibility, position, topic, intents, status, tags and whether the plan still covers each prompt. stats summarises the set and names the top performer; planCoverage is present when the plan has stopped funding some prompts.

---

​

echod_get_prompt

One prompt in depth. Pair it with echod_list_chats to read the actual answers behind the numbers. Also accepts the window parameters. Returns: the prompt’s KPIs with deltas, the per-brand visibility and position series, the share-of-voice split, each brand’s sentiment, the per-brand table (topBrands) and the domains retrieved most for this prompt (topDomains).

---

​

echod_list_chats

The individual AI answers (chats) collected for one prompt or one topic in the window, newest first. Give exactly one of promptId or topicId. Also accepts the window and paging parameters. pageSize defaults to 25 for this tool, and sortDir to desc (newest first). Returns: chat rows with which platform and region answered, whether the own brand was named and at what position, the brands named, a preview of the answer and the sources it used. Open one in full with echod_get_chat using its executionId and promptId.

---

​

echod_get_chat

One AI answer in full - the ground truth behind every metric. Returns: the answer text as markdown (answerMarkdown), every brand it named with position and sentiment (tracked brands under mentions, the rest under otherBrands), every page it retrieved under sources (with citedOrder set on the ones it visibly cited), the searches the engine ran (searchQueries), and any product, ad, map or video blocks it showed. positionBasis says whether positions were ranked among all brands named or only tracked ones.

---

​

echod_list_citation_domains

The domains AI engines retrieved while answering the project’s prompts in the window. Also accepts the window and paging parameters. Returns: domain rows with the domain’s type (You is the own site, Competitor the site of a brand the project knows, then UGC, Corporate, Editorial, Reference, Institutional, Other, Unclassified), the share of answers that retrieved it, URLs retrieved per answer, citations per retrieving answer, and the gap score - how many competitors were named next to it while the own brand was not. A higher gap score means a better outreach target.

---

​

echod_get_citation_domain

One domain in depth for the window. Also accepts the window parameters. Returns: the domain’s retrieval trend, the topics it was retrieved for most, the split by platform, and every URL of it that was retrieved, with citations, type and the prompts’ topics.

---

​

echod_list_citation_urls

The individual pages AI engines retrieved in the window. To audit your own site’s pages, set search to the project’s website domain; sort by gapscore to find competitor content worth answering. Also accepts the window and paging parameters. Returns: page rows with the page type (Homepage, Category Page, Product Page, Listicle, Comparison, Profile, Alternative, Discussion, How-To Guide, Article, Other), the domain type, how many answers retrieved it, citations per retrieval, how many brands were named next to it, and the gap score.

---

​

echod_get_citation_url

One page in depth for the window. Also accepts the window parameters. Returns: the page’s retrieval and citation metrics with trends, the split by platform, the brands named next to it with how often, and the prompts whose answers retrieved it.

---

​

echod_list_brands

The brands Echod knows for the project besides the own brand: tracked competitors (the ones the comparison tables chart) and untracked brands the crawl discovered in answers. Returns: each brand with its website, where it came from (UserAdded or AutoDiscovered), how many answers named it in total and in the current and previous mention windows, and its aliases. Untracked brands carry mention counts only: to compare one on visibility, position or sentiment it has to be tracked first.

---

​

echod_get_shopping_overview

The Shopping overview for a window: how often AI answers show product cards, how often yours are among them, and whose products appear instead. The natural starting point for product questions. The shopping tools count product cards (a carousel or an inline card), never a product merely named in prose - product visibility and brand visibility are different measures. Also accepts the window parameters. Returns: the metric tiles (shoppingChatShare is the share of answers that showed any product card, visibility the share of those that showed one of your products, winRate how often one of your products was the first card, position its average card position), the brands ranked by product visibility with share of voice, position, win rate and appearances, the product cards (top by visibility, losingGround by visibility drop, neverShown catalog products no answer has shown), and the movers for query fan-outs, the merchants answers send shoppers to, and the sources read in answers that showed products. hasCatalog false means the project uploaded no catalog, so every product is one an answer showed.

---

​

echod_list_products

The products grid for a window, one row per product - yours, competitors’ and any other product the answers showed. Also accepts the window and paging parameters. sortDir defaults to desc. Returns: product rows with the brand (isOwn for your own brand, competitorId when it is a tracked competitor), whether the product is in the uploaded catalog (isCatalog), its category, visibility, win rate, average card position, deltas against the preceding window, the catalog price and the latest price an answer quoted (aiPrice), the top merchants selling it, and appearances (answers whose cards showed it). summary aggregates the rows under the filter; categories is the tree with product counts. Each row’s productId opens echod_get_product.

---

​

echod_get_shopping_filters

The products page’s filter options for a window. The assistant calls it once before filtering the product list by brand or merchant. Also accepts the window parameters. Returns: the category tree with product counts, the brands (your own brand first, then by appearances, with isOwn and each brand’s product count) and the merchants (by appearances, with how many distinct products each sold), each with the exact name echod_list_products filters by. shoppingDataSince is the first crawl date with product cards.

---

​

echod_get_product

One product in depth for a window - for “why is this product losing ground” questions. Also accepts the window parameters. Returns: the header (title, brand, catalog membership, category path, catalog price), the tiles (visibility, win rate, position, appearances, rating, price), the per-crawl trend, the competing products shown in the same carousels with their share, the position box plot against them, the merchants selling it, the query fan-outs and common search terms in answers that showed it, the sources read in those answers, and prompts: every tracked prompt whose answers showed the product, with its visibility, position, win rate and appearances there. A product the catalog holds but no answer ever showed answers with zeros.

---

​

echod_list_product_chats

The AI answers that showed a product as a card in the window, newest first. The last step before reading an answer in full. Also accepts the window and paging parameters. pageSize defaults to 10 for this tool. Returns: chat rows with the prompt, platform, region and run date, the card’s position, the title and price the answer printed, the merchant it linked, the opening of the answer text, the other products shown beside it (coProducts) and the brands named alongside (coBrands). Each row’s executionId and promptId are the arguments echod_get_chat takes to read that answer in full.

---

​

echod_get_docs

Short reference text for interpreting Echod’s numbers. The assistant reads metrics before explaining a metric to you, and shopping before explaining a product number. Returns: { topic, title, content } with the reference text.