# Report tools

These tools cover the **public-report** surface of the MCP server: anything you can reach with a report's public token, plus the tools that list your organization's reports so you can find one.

There are three groups:

- **AI Visibility** — the full report behind a token: share of voice, grounding gaps, citations, and recommendations.
- **Site Readiness audit** — an audit's summary and per-page detail.
- **Discovery** — list your organizations and their reports to get tokens in the first place.

## Getting a public token

Every AI Visibility report and Site Readiness audit has a **public token** in its share URL. Two ways to get one:

- **From a share link** — the token is the identifier in the report's shareable URL.
- **From your account** — call `list_reports` (below) to list your organization's reports along with their tokens.

<Callout>
An AI Visibility report must be **unlocked** for these tools to return data. A locked report returns *"This AI Visibility report has not been unlocked yet."* Site audits return data once the audit has completed.
</Callout>

## AI Visibility

All four take a single `publicToken`. Start with `get_ai_visibility_report` for the overview, then drill into the others for full detail.

### `get_ai_visibility_report`

The full report: brand summary, share of voice, citations, per-platform breakdown, competitor gaps, technical readiness, and top-line recommendations. This is the natural first call.

| Parameter | Type | Notes |
|---|---|---|
| `publicToken` | string | The report's public token. |

### `get_ai_visibility_grounding`

The full grounding analysis: every **gap opportunity** ranked by gap score (searches where the brand doesn't rank but competitors do), plus the searches where the brand already ranks. Use it to find specific content opportunities.

Searches the model scoped to one site with the `site:` operator (`site:example.com pricing`) are listed apart, in `siteScopedSearches`, and counted in `summary.siteScoped` as `own` / `competitor` / `thirdParty`. They are kept out of the gap opportunities on purpose: nothing can rank for a query aimed at a single domain, so they are **evidence about which sites the model already trusts**, never targets to optimize for.

### `get_ai_visibility_citations`

The citation breakdown: counts by media type, authority type, content format, and page type, plus the most-cited brand pages and the third-party pages that mention the brand.

### `get_ai_visibility_recommendations`

The full, role-categorized recommendations:

- **SEO / AEO** — search terms to rank for.
- **PR** — sites to pitch, where competitors are cited but the brand isn't.
- **Technical** — fixes to improve machine readability.
- **Brand consistency** — issues by platform.
- **Strategy** — how to address low share of voice.

## Site Readiness audit

The audit tools are a drill-down chain: **summary → page list → single page.**

### `get_site_audit_summary`

The audit overview: overall and per-dimension scores, priority issues, strengths, improvements, and next steps.

| Parameter | Type | Notes |
|---|---|---|
| `publicToken` | string | The audit's public token. |

### `list_site_audit_pages`

List the audit's analyzed pages — paginated, sortable, and filterable. Returns each page's `id`, path, intent, and per-dimension scores. Sort ascending by `overallScore` to find the weakest pages first.

| Parameter | Type | Notes |
|---|---|---|
| `publicToken` | string | The audit's public token. |
| `page` | number | Zero-based page index. |
| `pageSize` | number | 1–100. |
| `sortBy` | string | e.g. `overallScore`, `staticContentScore`. |
| `sortOrder` | `asc` \| `desc` | |
| `intentFilter` | string | Filter by page intent. |
| `search` | string | Substring match on URL/path. |
| `minScore` / `maxScore` | number | 0–100 score bounds. |

### `get_site_audit_page`

Full detail for one page (use a `pageId` from `list_site_audit_pages`): per-dimension scores and summaries, findings, technical metrics, and chunk / citation-readiness analysis.

| Parameter | Type | Notes |
|---|---|---|
| `publicToken` | string | The audit's public token. |
| `pageId` | string | The page id from `list_site_audit_pages`. |

## Discovery: find your reports

These use your signed-in account (no token needed) to help you locate a report's token.

### `list_my_organizations`

Lists the Spyglasses organizations you belong to, and your role in each. Use a returned `organizationId` with `list_reports` when you belong to more than one.

### `list_reports`

Lists an organization's AI Visibility reports and site audits, each with its **public token**. Defaults to your organization; if you belong to more than one, pass an `organizationId` from `list_my_organizations`. Feed the returned tokens into the token-scoped tools above.

| Parameter | Type | Notes |
|---|---|---|
| `organizationId` | string (optional) | Which organization to list. Omit if you have only one. |

## A typical flow

<Steps>

<Step>
`list_reports` → pick a report and copy its `publicToken`.
</Step>

<Step>
`get_ai_visibility_report` (or `get_site_audit_summary`) for the headline picture.
</Step>

<Step>
Drill in: `get_ai_visibility_grounding` / `get_ai_visibility_citations` / `get_ai_visibility_recommendations`, or `list_site_audit_pages` → `get_site_audit_page` for the worst pages.
</Step>

</Steps>

Or skip the manual steps and run the **Analyze a report**, **What should I fix first?**, or **Find my weakest pages** [prompts](/docs/mcp/prompts).

## Related

- [AI Visibility Reports dashboard](/docs/dashboards/ai-visibility-reports) — the dashboard these tools mirror
- [AI Readiness Audit dashboard](/docs/dashboards/ai-readiness-audit) — the site audit dashboard
- [Prompts](/docs/mcp/prompts) — `analyze_report`, `what_to_fix_first`, `competitor_gaps`, `audit_worst_pages`