Tool reference
The 14 Scope agent tools.
The public API-of-record for the Scope MCP server. Every tool below is available at the same endpoint over Streamable HTTP.
See
whoamirequires readFreeReturns plan, remaining checks, committed burn, auto-upgrade state, and rate-limit status.
list_businessesrequires readFreeLists businesses on the account with their latest snapshot and scheduled burn.
get_visibility_reportrequires readFreeReturns the overall visibility score, per-engine breakdown, and trend over time.
get_prompt_resultsrequires readFreeReturns paginated, prompt-level measurements and cadence.
get_citationsrequires readFreeReturns cited sources across engines and competitor citation gaps.
get_competitorsrequires readFreeReturns the measured competitor set and share-of-voice signals.
get_recommendationsrequires readFreeReturns prioritized fixes with their expected impact.
get_readiness_scorerequires readFreeScores a website’s readiness for AI visibility; a limited anonymous check is available with no login.
Do
add_businessrequires business:writeFreeIdempotently adds a business by normalized domain.
run_scanrequires scan:run1 check per tracked promptRuns every tracked prompt across all supported engines.
check_promptrequires scan:runExactly 1 checkTests a single prompt across engines without tracking it.
track_promptrequires scan:runFree now — adds committed burnCommits a prompt to monthly or weekly monitoring for a business.
untrack_promptrequires scan:runFreeRemoves a tracked prompt from a business, reducing committed burn.
Fix
generate_fixrequires readFreeDrafts schema, FAQ, or content from a recommendation; never writes to the site.
complete_recommendationrequires business:writeFreeMarks a recommendation complete with an optional note, for before/after attribution.
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 — relay them to the human, and warn at 80% pool use.
There is no publish_fix tool. Scope agents draft fixes; they never publish directly to a website or CMS.
Error shapes
Every error returns a JSON-RPC error with a stable machine-readable code.
| 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.
15 tools total. See the full setup flow, example prompts, and trust model.
Back to Scope for agents