# 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.

### `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`