> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Every tool the Echod MCP server exposes, with parameters and response fields.

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.

> [!NOTE]
>
> All tools except `echod_list_projects` and `echod_get_docs` require a `projectId`. Your assistant handles this automatically after you pick a project.

## Shared parameters

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

### Window parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `period` | string | No | Window preset: `7d`, `30d`, `60d` or `90d` (days ending today), or `custom` with `from` and `to`. Defaults to `30d`. |
| `from` | string | No | Inclusive start date, `YYYY-MM-DD`, for a custom window. Must fall within the last 90 days. |
| `to` | string | No | Inclusive end date, `YYYY-MM-DD`, for a custom window. Defaults to today. |
| `platform` | string | No | Restrict to one AI platform: `chatgpt`, `perplexity`, `google_aimode`, `google_aioverview`, `copilot` or `gemini`. Omit for all platforms combined. Only platforms the project offers are accepted - `echod_get_project` lists them. |
| `region` | string | No | Restrict to one region as an ISO 3166-1 alpha-2 country code, for example `US`. Omit for all regions combined. Only regions the project offers are accepted. |

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page` | number | No | 1-based page number. Defaults to 1. |
| `pageSize` | number | No | Rows per page, 1 to 100. Defaults to 20 (25 for chats, 10 for product chats). |
| `sortDir` | string | No | `asc` or `desc`. |

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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `organizationId` | string | No | Restrict to one organization. Omit to list every project you can access. |

**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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |

**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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |

**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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `groupBy` | string | No | `none` for one table (default), or `platform`, `region` or `topic` for one group per platform, region or topic. Grouping by platform cannot be combined with a `platform` filter, nor region with `region`. |
| `maxCompetitors` | number | No | Competitors per group, ranked by visibility, 1 to 20. Defaults to all of them. |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `search` | string | No | Case-insensitive text to match against the topic |
| `status` | string | No | `Active` or `Paused`. Omit for both. |
| `scoreFilter` | string | No | Visibility band: `high` (score 66 and above), `medium` (33 to 65) or `low` (below 33) |
| `sortBy` | string | No | `title` (default), `score`, `shareofvoice`, `averageposition`, `trend`, `prompts`, `sentiment`, `lastcrawled`, `status` or `createdat` |
| `includePrompts` | boolean | No | Include each topic's nested prompt rows. Defaults to false. |
| `includePlatformStates` | boolean | No | Include the per-platform states on each row. Defaults to true. |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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".

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `topicId` | string | Yes | The topic id from `echod_list_topics` |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `topicId` | string | No | Only prompts of this topic (id from `echod_list_topics`) |
| `search` | string | No | Case-insensitive text to match against the prompt |
| `intent` | string | No | A specific intent (`Comparison`, `Alternative`, `Review`, `Recommendation`, `Pricing`, `Purchase`, `HowTo`, `Troubleshooting`, `Guide`, `Local`) or a macro intent (`Informational`, `Navigational`, `Commercial`, `Transactional`, `Local`) |
| `status` | string | No | `Active` (crawled), `Suggested` (proposed, not crawled) or `Archived`. Omit for all. |
| `sortBy` | string | No | `visibility` (default), `position`, `prompt`, `topic`, `intent`, `status`, `createdat` or `lastcrawled` |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `promptId` | string | Yes | The prompt id from `echod_list_prompts` |

Also accepts the [window parameters](#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`.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `promptId` | string | One of | List the answers to this prompt (id from `echod_list_prompts`) |
| `topicId` | string | One of | List the answers to every prompt of this topic (id from `echod_list_topics`) |
| `mentionedOnly` | boolean | No | Only answers that named the own brand. Defaults to false. |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `promptId` | string | Yes | The prompt the answer belongs to (`promptId` on the chat row) |
| `executionId` | string | Yes | The answer's `executionId` from `echod_list_chats` |

**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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `search` | string | No | Case-insensitive text to match against the domain |
| `domainType` | string | No | Only domains of this type, one of the response's `typeOptions` values |
| `sortBy` | string | No | `retrieved` (default), `source`, `domaintype`, `retrievalrate`, `citationrate` or `gapscore` |
| `includeWidgets` | boolean | No | Include the retrieval trend, the movers (top, new, trending, losing) and the type split. Defaults to false. |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `domainHash` | string | Yes | The domain's hash (`domainHash`) from `echod_list_citation_domains`, a topic's or prompt's `topDomains`, or a competitor ranking row |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `search` | string | No | Case-insensitive text to match against the URL |
| `urlType` | string | No | Only pages of this type, one of the response's `typeOptions` values |
| `sortBy` | string | No | `retrievals` (default), `url`, `urltype`, `domaintype`, `citationrate`, `mentions` or `gapscore` |
| `includeWidgets` | boolean | No | Include the trend, movers and type-split widgets. Defaults to false. |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `urlHash` | string | Yes | The page's hash (`urlHash`) from `echod_list_citation_urls` or a domain detail's URL rows |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `isTracked` | boolean | No | `true` for tracked competitors only, `false` for untracked discovered brands only. Omit for both, tracked first. |
| `search` | string | No | Match against the name and website |
| `sortBy` | string | No | `recent`, `name`, `mentions` or `rising` (fastest-growing mention count). Omit to keep the project's own order. |
| `page` | number | No | 1-based page number |
| `pageSize` | number | No | Rows per page. Omit to return everything that matched. |

**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.

> [!NOTE]
>
> The mention counts run from `mentionWindowStartedAt`, not from the analytics window, so a tracked brand can show 0 here and a visibility above zero in `echod_get_brand_report` for the same 30 days. For window metrics use the brand report.

***

## 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `catalog` | string | No | Which products count: `all` (default) is every product the project knows, the uploaded catalog plus every product an answer showed; `mine` is only the uploaded catalog (Shopify or CSV import). |
| `includeTimeseries` | boolean | No | Include each brand's per-crawl visibility, win rate and position lines. Defaults to false. |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `search` | string | No | Case-insensitive text to match against the product title or brand |
| `brand` | string | No | Only products of this brand, the exact name from `echod_get_shopping_filters` |
| `merchant` | string | No | Only products this merchant sold in an answer, the exact name from `echod_get_shopping_filters` |
| `categoryId` | string | No | Only products in this category or its subcategories, an id from the category tree |
| `catalog` | string | No | `all` (default) or `mine`, as on the overview |
| `sortBy` | string | No | `appearances` (default), `visibility`, `winRate`, `position`, `catalogPrice`, `aiPrice`, `name` or `brand` |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `productId` | string | Yes | The product id from `echod_list_products` or the overview's product cards |

Also accepts the [window parameters](#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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | The project id from `echod_list_projects` |
| `productId` | string | Yes | The product id from `echod_list_products` or the overview's product cards |

Also accepts the [window](#window-parameters) and [paging](#paging-parameters) 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.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `topic` | string | Yes | `metrics` (how visibility, share of voice, position, sentiment and deltas are defined), `filters` (periods, platforms, regions, the resolved window), `citations` (retrieval and citation rates, gap score, domain and URL types), `shopping` (product cards: shopping chats, appearances, visibility, win rate, position, the catalog toggle, brands and merchants), `platforms` (vocabularies: platform values, intents, statuses, brands) or `limits` (history depth, paging, rate limits, error codes) |

**Returns:** `{ topic, title, content }` with the reference text.

> [!NOTE]
>
> The same reference text is also published as MCP resources under `echod://docs/...`, for clients that support resources.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.