list_prompt_outcomes
Read only
This page as markdown, for an agentPer tracked question, what the engines did in the current sweep: cited (used one of your pages as a source), named (mentioned you, sourced elsewhere), category-only (answered the category and named a competitor instead of you) or absent. Each question carries n (answers pooled), the counts, the cited share with its Wilson interval, and the split per engine. Worst first, so the questions you lose come first. No sweep means not measured, never zero.
When to use it
- Use it when: You need to know which tracked questions the brand loses, and on which engine.
- Not when: You need one headline share; that is get_answer_share.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| assetId | string | yes | The Visibility Asset UUID to query. |
| status | string | no | all (default), lost (category-only or absent answers exist), or cited (at least one cited answer). |
| limit | number | no | Maximum items to return; default 100, at most 500. |
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. |
| available | False when no measured citation sweep exists; nothing here is zero then. |
| collectedAt | When the snapshot these values come from was collected. Absent when there is no snapshot. |
| snapshotsPooled | How many snapshots the current sweep's answers came from. More than one means part of it replayed from cache. |
| competitorCount | Confirmed competitors on the asset. Zero leaves category-only and absent unmeasurable, not negative. |
| windowMs | How far back from the sweep's newest answer its runs were pooled: the citation freshness window. |
| prompts | Worst first. Each with promptText, n, counts (cited, named, category_only, absent, unclassified, total), citedShare with its interval, lost, and byEngine. |
| total | How many questions the sweep holds before the status filter and the limit. |
| note | What each outcome class means, and why unclassified is never folded into absent. |
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_prompt_outcomes",
"arguments": {
"assetId": "<assetId from list_assets>",
"status": "<status>",
"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_prompt_outcomes for my site with status lost. Which questions do we lose most, on which engine, and 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.