whoami or list_brands first — the brand_id values they return are what the other tools expect.
The tools fall into three groups:
Resolver tools
whoami
Returns your key’s identity: its scopes and the brands it can access.
list_brands
The brands your key can access, with names and websites. A single-brand key returns one; an agency (multi-brand) key returns all granted brands — loop over these to run a report per brand.
list_dimensions
Args: brand_id
The filterable dimensions for a brand: the AI platforms tracked, the competitors configured, and the topics covered. Use these to scope other tools.
Metric tools
These query Cited’s conformed metrics cube. They return the same numbers as the dashboard — one name, one formula, across every surface.list_metrics
No arguments. Returns the valid metric and breakdown values that cube_slice and cube_drill accept. Call this to ground yourself rather than guessing metric names — an unknown metric is a tool error, not an empty result.
The metrics
These are the same definitions the dashboard shows, under the cube’s key names.visibility is the cube’s key for the measure the dashboard labels Mention Rate. Same formula, same number — the key name is older than the label.citation_rate has no source dimension. Its denominator is responses mentioning the brand, so domain is refused as either a filter or a breakdown — the call errors and tells you to use citation_share instead. See citation rate and citation share for the concepts.The breakdown dimensions
platform · domain · topic · intent · prompt · run_date
The same names work in filters, as equality or in constraints — e.g. {"platform": "chatgpt"} or {"topic": "personal loans"}.
cube_slice
Args: brand_id, metric, breakdown (optional), filters (optional), days (default 30), limit (default 50)
Compute one canonical metric over a slice, optionally broken down by a dimension.
numerator and denominator, so you can always see what a percentage was computed against — and spot a thin sample before you act on it.
Two metrics return a different shape.
net_sentiment returns a sentiment object with its component counts instead of rows. sov ignores your breakdown and always keys rows by competitor, with your own brand on the reserved key __brand__.cube_drill
Args: brand_id, filters (optional), breakdown (default page), days (default 30), limit (default 25), offset (default 0)
Recursive drill-down. Returns an entity’s citation share plus a trend and a breakdown, where each child carries share-of-parent and global share — so you can tell “half of this domain’s citations come from one page” apart from “this page is half of all our citations.”
Chain filters to nest: drill a domain, then break that domain down by page or platform. This is the same primitive behind the dashboard’s drill drawers.
cube_category_mix
Args: brand_id, filters (optional), days (default 30), per_platform (default true)
Citation Mix — citation share across the six source categories (owned, competitor, earned_media, aggregator, community, other), overall and per AI platform.
This is the source-type breakdown that cube_slice’s domain dimension cannot give you: every cited domain is classified at read time and rolled up. Set per_platform: false for the overall mix only.
Read tools
These are separate data domains. They are not cube-conformed, so do not expect their numbers to reconcile againstcube_slice.
get_ai_shelf_products
Args: brand_id, days (default 30), platform (optional), limit (default 50)
The products AI shopping answers show for your brand’s category — title, position, whether it’s you vs a competitor, merchant, price, platform, and topic.
Requires the Scale plan or higher (or a per-brand override).
get_cited_index
Args: edition (optional — latest if omitted), category (optional — id, slug, or name), top_n (default 10)
The Cited Index — India’s AI-visibility ranking of brands across categories and LLMs. Market-wide data (not scoped to your brand); any valid key can read it. Returns the top brands per category for an edition.
get_index_source_mix
Args: editions (optional — latest if omitted), category (optional), top_n (default 15), per_engine (default true)
Which kinds of sources AI engines cite in a category, market-wide. Returns a 5-bucket mix (brand_site, earned_media, aggregator, community_social, other) overall and per engine, plus the top cited domains.
Pass an explicit list to editions to pool public editions — counts sum, they are never averaged.
get_index_source_mix and cube_category_mix are different measurement systems. One is market-wide with 5 buckets; the other is brand-scoped with 6 (it adds competitor, and splits differently). The numbers are not interchangeable and should never be compared directly or presented side by side as if they were the same measure.Coming soon
- Action tools — generate a content brief, find source targets, create a task: run Cited’s execution layer from your assistant.
Errors
Tools return an error (surfaced as an MCP tool error) when: the API key is missing/invalid/expired or revoked (Invalid API key), the key isn’t granted the requested brand (API key not granted this brand), the plan doesn’t include the feature (e.g. AI Shelf requires the Scale plan or higher), a metric or breakdown name isn’t recognised (Unknown metric '…'. Call list_metrics for valid metrics.), or a rate limit is hit (Rate limit exceeded).