API and MCP
MCP tools
Every tool the Botlum MCP server offers, with its inputs and a question that uses it.
All tools only read. Dates are yyyy-MM-dd; without them a tool covers the last 30 full days, and a range covers at most 92 days.
Engines are the keys chatgpt_search, gemini, google_ai_overviews and google_ai_mode;
countries are two-letter codes such as DE. You rarely need to know this: the assistant picks the tools and fills the inputs from
your question.
list_projects
The brands this workspace tracks: each project's id, name, domain, other names and competitors. Start here: every other tool takes a project id.
Try: “Which brands do we track in Botlum?”
get_visibility_overview
How often AI answers name the brand and each competitor over a range: visibility (share of analysed answers that name the brand, 0..1), citation rate, share of voice, sentiment, the change against the previous range when comparable, and a per-engine breakdown. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “How visible were we in AI answers last month, and who did better?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys, e.g. chatgpt_search,gemini. |
countries | no | Comma-separated two-letter country codes, e.g. DE,US. |
get_visibility_trend
One point per day and engine, and per day across engines, for the brand or one competitor. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Show our visibility in ChatGPT day by day for the last two weeks.”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
brand | no | `project` for the brand, or `competitor:{id}` with an id from list_projects. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys. |
countries | no | Comma-separated two-letter country codes. |
compare_brands
The brand and each competitor over the range, overall and per engine: who AI names more, and where. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Compare us with our competitors on each engine.”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys. |
countries | no | Comma-separated two-letter country codes. |
get_visibility_matrix
Rows by prompt, by country or by topic, one cell per engine: which questions and markets the brand wins or loses. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Which of our prompts do we lose in Germany?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
by | no | `prompt` (default), `country` or `topic`. |
brand | no | `project` for the brand, or `competitor:{id}`. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys. |
countries | no | Comma-separated two-letter country codes. |
list_prompts
The questions tracked for a project, each with its country, language, status, topic and tags. Prompt ids feed get_answer.
Try: “List the prompts we track in the US.”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
get_answer
The answer one engine gave to one prompt on one day: its text, the sources it cited, the searches the engine ran, which brands it named and how (sentiment, recommended or merely listed), and where the brands stood on the search results page.
Try: “What exactly did Gemini answer to "best CRM for startups" yesterday?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
promptId | yes | Prompt id from list_prompts. |
engine | yes | Engine key, e.g. chatgpt_search. |
date | yes | The day, yyyy-MM-dd. |
list_cited_sources
The domains or pages AI answers cite, how often, and for which brands: where AI gets its information about this market. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Which sites do AI answers cite most for our market?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
kind | no | `domains` (default) or `pages`. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys. |
countries | no | Comma-separated two-letter country codes. |
get_source_gap
Domains cited in answers that name competitors but not the brand: the sites to get mentioned on. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Where are competitors cited and we are not?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |
engines | no | Comma-separated engine keys. |
countries | no | Comma-separated two-letter country codes. |
list_discovered_brands
Brands the answers name that the project does not track yet, most frequent first: likely competitors worth adding. Dates are yyyy-MM-dd; without them, the last 30 full days. A range covers at most 92 days.
Try: “Which brands do the answers name that we do not track?”
| Input | Required | Meaning |
|---|---|---|
projectId | yes | Project id from list_projects. |
from | no | First day, yyyy-MM-dd. |
to | no | Last day, yyyy-MM-dd. |