list_competitors
Read only
This page as markdown, for an agentThe competitors tracked on an asset and, per engine, how many sampled answers cited the rival where the brand was not cited, as a share with its n and Wilson interval. Call it before propose_competitor, so you do not propose one that is already tracked. An empty list is a fact about the tracked set, not a measurement.
When to use it
- Use it when: You need the tracked rivals, and how often each is cited where the brand is not.
- Not when: You are about to invent a competitor name, or to propose one without checking it is not already tracked.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| assetId | string | yes | The Visibility Asset UUID to query. |
| limit | number | no | Maximum items to return; default 50, at most 200. |
What comes back
Every field this tool can return. Checked against the handler on a real database in the test suite, not typed from memory.
| Field | Meaning |
|---|---|
| assetId | The asset asked about, echoed back. |
| dataStatus | One of ok, not_measured or empty_filter. not_measured means no measurement of this kind exists yet, which is not zero; empty_filter means data exists and your filter matched none of it. |
| href | The dashboard page that holds the evidence behind this result, for the right site. A signed-in person can open it; quote it beside the numbers. |
| competitors | Each with competitorId, name, domain, createdFrom and byEngine: wins (answers citing the rival and not you), engineRuns, and that as a share with n and interval. |
| winsMeasured | False when no sampled answer exists yet, so no byEngine block carries a number. |
| note | What a win is, and why an empty tracked set is a fact rather than a measurement. |
What comes back with the number
Shares arrive with the sample size behind them and a 95% Wilson interval. Values carry a provenance of measured, estimated or derived. A pillar that was not measured reports as not measured rather than as zero, and the composite Visibility Score is held until at least 5 of its 7 pillars are measured.
Example request
The wire shape, from the schema. Every argument is a placeholder.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_competitors",
"arguments": {
"assetId": "<assetId from list_assets>",
"limit": "<number>"
}
}
}What dataStatus means
ok: There is at least one result, or a measured zero.not_measured: No measurement of this kind exists yet for the asset. Not zero, and not a broken connection.empty_filter: Data exists, and the filter you passed matched none of it. Retry without the filter.
Example prompt
Call list_competitors for my site. Which rival is cited instead of us most often, on which engine, with what n?
Calling it
Connect the MCP server at https://app.seoaio.ai/api/mcp over the Streamable HTTP transport. Per-customer authentication is required, so nothing is exposed without it. Call list_assets first: every other tool needs an assetId from it.
Next
For an agent
Read the skill at /SKILL.md before calling anything. It carries the tool order and the rules for quoting a number, including the one that matters most: quoting a share without its interval overstates what we measured.