# Scope Agent Tool Reference

> The public API-of-record for the Scope MCP server. 15 tools, all available over Streamable HTTP at https://scope.online/mcp.

Canonical page: https://scope.online/agents/tools

## See

### `whoami`
Returns plan, remaining checks, committed burn, auto-upgrade state, and rate-limit status.
- Cost: Free
- Requires permission: `read`

### `list_businesses`
Lists businesses on the account with their latest snapshot and scheduled burn.
- Cost: Free
- Requires permission: `read`

### `get_visibility_report`
Returns the overall visibility score, per-engine breakdown, and trend over time.
- Cost: Free
- Requires permission: `read`

### `get_prompt_results`
Returns paginated, prompt-level measurements and cadence.
- Cost: Free
- Requires permission: `read`

### `get_citations`
Returns cited sources across engines and competitor citation gaps.
- Cost: Free
- Requires permission: `read`

### `get_competitors`
Returns the measured competitor set and share-of-voice signals.
- Cost: Free
- Requires permission: `read`

### `get_recommendations`
Returns prioritized fixes with their expected impact.
- Cost: Free
- Requires permission: `read`

### `get_readiness_score`
Scores a website’s readiness for AI visibility; a limited anonymous check is available with no login.
- Cost: Free
- Requires permission: `read`

## Do

### `add_business`
Idempotently adds a business by normalized domain.
- Cost: Free
- Requires permission: `business:write`

### `run_scan`
Runs every tracked prompt across all supported engines.
- Cost: 1 check per tracked prompt
- Requires permission: `scan:run`

### `check_prompt`
Tests a single prompt across engines without tracking it.
- Cost: Exactly 1 check
- Requires permission: `scan:run`

### `track_prompt`
Commits a prompt to monthly or weekly monitoring for a business.
- Cost: Free now — adds committed burn
- Requires permission: `scan:run`

### `untrack_prompt`
Removes a tracked prompt from a business, reducing committed burn.
- Cost: Free
- Requires permission: `scan:run`

## Fix

### `generate_fix`
Drafts schema, FAQ, or content from a recommendation; never writes to the site.
- Cost: Free
- Requires permission: `read`

### `complete_recommendation`
Marks a recommendation complete with an optional note, for before/after attribution.
- Cost: Free
- Requires permission: `business:write`

## The checks contract

A check is one prompt evaluated across all supported engines. `check_prompt` spends exactly one check. `run_scan` spends one check per tracked prompt included.
Adding a prompt with `track_prompt` is free at that moment — its cadence creates committed burn (monthly cadence commits 1 check/month; weekly commits about 4/month).
Every response that spends checks returns `checks_spent` and `checks_remaining`. There is no `publish_fix` tool — Scope agents draft fixes, they never publish directly to a website or CMS.

## Error shapes

| code | status | meaning |
|---|---|---|
| `invalid_request` | 400 | Malformed or missing required arguments. |
| `unauthorized` | 401 | Missing, expired, or invalid API key / OAuth token. |
| `insufficient_scope` | 403 | The key or token is missing a required permission (e.g. business:write). |
| `tier_locked` | 403 | The account is not on Growth. Relay the returned upgrade_url and stop. |
| `not_found` | 404 | The business, prompt, or recommendation ID does not exist on this account. |
| `rate_limited` | 429 | Too many requests. Respect retry_after (seconds) before retrying. |
| `quota_exceeded` | 402 | The account's check pool is exhausted. Do not retry or split the action. |
| `over_committed` | 402 | Existing tracked prompts already exceed the plan pool. Offer to reduce cadence. |
| `internal_error` | 500 | Unexpected server error. Safe to retry once. |

## Rate limits

- **Read tools:** 60 requests / 60 seconds (per authenticated user)
- **Action tools:** 10 requests / 60 seconds, 500 / day (per authenticated user)
- **Anonymous readiness check:** 5 requests / 24 hours (per source IP)

A `rate_limited` response includes `retry_after` in seconds.