ai_visibilityUnderstandRead-only
How AI assistants answered the project's monitored prompts in one completed, measured scan run: mention rate, average position, sentiment, competitors and citations, per provider and per prompt, plus the inferred ICP against the declared one. This evidence is probabilistic: read the warnings before drawing conclusions. Read-only.
- Inputs
- runId (required) — A completed scan run id (from recent_scans).
- Returns
- Mention rate, position, sentiment, competitors and citations per provider and prompt.
attach_follow_upProveChanges shared data
Attach a completed scan, run after the action's follow-up date, as the evidence for a recorded change. Then compare it with did_it_improve or compare_runs and, if the user agrees, mark the action implemented with update_recommendation. Reusing the same idempotencyKey is a safe retry.
- Inputs
- actionId (required) — The tracked action id.; followUpRunId (required) — A completed scan run started after the follow-up date.; idempotencyKey (required) — Unique key for this write (e.g. a UUID). Reuse it to retry safely.
- Returns
- The action with its follow-up evidence attached.
compare_runsProveRead-only
Compare a completed run with the active baseline (or a given baseline run): site-audit findings that are new, resolved or materially changed; per-prompt AI answer changes (mention, position, sentiment, abstention, citations); ICP dimensions added or removed. The comparison may be partial or incomparable; the warnings say why. Needs an active baseline (set_baseline) unless baselineRunId is given. Read-only.
- Inputs
- currentRunId (required) — Completed run to compare.; baselineRunId (optional) — Completed run to compare against; defaults to the active baseline.; limit (optional) — Maximum changed items to list per section.
- Returns
- Findings, per-prompt answer changes and customer-profile changes, with warnings.
describe_operationDiscoverRead-only
Show one operation's parameters and request-body shape. Discovery only: operations are not directly callable. Use the workflow tools; if none covers this, the operation is a candidate for a new Arazzo workflow.
- Inputs
- operationId (required) — An operationId from search_operations.
- Returns
- Parameters and request shape.
did_it_improveProveRead-only
Headline answer to "did it improve?" for a completed scan run (default: the newest completed run) against its comparison basis: open, new and resolved site issues, AI mention rate and average position, ICP changes, plus whether anything moved and how comparable the runs are. Always report the warnings: partial or incomparable runs, and small AI samples, limit what the numbers can show. Use compare_runs for the item-level detail. Read-only.
- Inputs
- currentRunId (optional) — Completed run to judge; defaults to the newest completed run.
- Returns
- Issues, mention rate, position, profile changes and how comparable the runs are.
plan_scanScanRead-only
Price a scan of the selected project without spending anything: returns the credit cost with line items, what will run, the prompts a full scan measures, and a planHash. Show the price to the user and get explicit approval before calling start_scan with the same mode, maxPages and planHash. Credits come from the project owner's balance.
- Inputs
- mode (required) — crawl_only: site audit only (cheapest). site_icp: site audit plus ICP inference. full: also measures AI answers to the project's monitored prompts (costs the most).; maxPages (optional) — Crawl tier: pages to audit (25, 50, 100, 150, 200 or 250). More pages cost more.
- Returns
- Credit cost with line items, what will run, the prompts, and a planHash.
project_overviewUnderstandRead-only
Describe the selected project (domain, markets, topics, declared ICP, providers, scan frequency, last scan, your workspace role) together with its active baseline and recent baseline history. Read-only. Start here for context, then use recent_scans to find run ids.
- Inputs
- historyLimit (optional) — How many past baseline selections to include.
- Returns
- Project settings, last scan time, active baseline and baseline history.
recent_scansUnderstandRead-only
List the selected project's scan runs, newest first, with stage, mode (full, site_icp, crawl_only), page allowance, prompt count, providers and any failure. Use the run ids with recommendations, site_health, ai_visibility, set_baseline and did_it_improve. Read-only.
- Inputs
- limit (optional) — Maximum runs to return.; stage (optional) — Only completed or only failed runs.
- Returns
- Run ids you pass to the other tools.
recommendation_actionsProveRead-only
List the project's tracked recommendation actions (the to-do list made from scan recommendations), newest first, with counts per state (new, accepted, implementing, implemented, dismissed), each action's recommendation title and any recorded change. Read-only.
- Inputs
- state (optional) — Only actions in this state.; limit (optional) — Maximum actions to list.
- Returns
- Tasks newest first.
recommendationsUnderstandRead-only
The prioritised recommendations heyEO produced from one completed scan run, highest priority first, each with its source (site_audit, ai_visibility, icp_drift), effort, evidence count, remediation and affected URLs. To start tracking one, pass runId, artifactId and the item's index to track_recommendation. Read-only. A RUN_NOT_COMPLETE / 409 error means the run has not finished.
- Inputs
- runId (required) — A completed scan run id (from recent_scans).; source (optional) — Only recommendations from this source.; limit (optional) — Maximum recommendations to return.
- Returns
- Recommendations with source, effort, evidence, fix and affected pages.
- Errors
- RUN_NOT_COMPLETE while the scan is still running.
record_changeProveChanges shared data
Record that a change was made on the site for a tracked action: the https URL that changed, when (default now) and how many days until a follow-up scan can show its effect (default 7). Each action takes one change. After the follow-up date, run a scan and attach it with attach_follow_up. Confirm with the user first. Reusing the same idempotencyKey is a safe retry.
- Inputs
- actionId (required) — The tracked action id.; changeUrl (required) — The https URL of the page that changed.; implementedAt (optional) — When the change went live (UTC ISO 8601); defaults to now.; eligibleDays (optional) — Days until a follow-up scan is eligible (default 7).; idempotencyKey (required) — Unique key for this write (e.g. a UUID). Reuse it to retry safely.
- Returns
- The recorded change and its follow-up date. One change per action.
scan_statusScanRead-only
Report a scan run's stage, progress and status (running, complete, cancelled, failed, insufficient_credits) with a plain next step. Use it to follow a scan started with start_scan. Scans take minutes: pass waitSeconds (up to 90) to let the server wait for a terminal status instead of looping rapidly; keep it at or below 45 unless your client allows long tool calls. A POLL_EXHAUSTED warning means the scan is still running — call again. Read-only.
- Inputs
- runId (required) — The scan run id (a UUID, from start_scan or recent_scans).; waitSeconds (optional) — Seconds to wait server-side for the scan to finish (polls every 5 s). 0 answers immediately.
- Returns
- Stage, progress, status and a plain next step.
- Errors
- POLL_EXHAUSTED means still running: call again.
search_operationsDiscoverRead-only
Search the heyEO session API's operations by keyword and optional tag. Discovery only: operations are not directly callable. Use the workflow tools; if none covers this, the operation is a candidate for a new Arazzo workflow.
- Inputs
- query (required) — Keywords, e.g. 'monitor performance' or 'results'.; tag (optional) — Restrict to an OpenAPI tag.; limit (optional) — Max results (default 15).
- Returns
- Matching operations.
select_projectUnderstandChanges selection
Switch this session to another heyEO project the signed-in user can open. Workflow tools act on the selected project.
- Inputs
- projectId (required)
- Returns
- The newly selected project. Every other tool acts on it.
set_baselineProveChanges shared dataOwner only
Make a completed scan run the project's baseline, the reference that did_it_improve and compare_runs measure against. Changes what everyone in the workspace sees as the baseline; confirm with the user first. Only the project owner can do this (others get a 404). Reusing the same idempotencyKey is a safe retry.
- Inputs
- runId (required) — A completed scan run id.; idempotencyKey (required) — Unique key for this change (e.g. a UUID). Reuse it to retry safely.
- Returns
- The new active baseline. Others get “not found”.
site_healthUnderstandRead-only
Deterministic site-audit findings from one completed scan run: whole-run pass/warn/fail counts plus the matching findings (check, category, severity, URL, evidence, recommendation). Defaults to failing checks. Read-only.
- Inputs
- runId (required) — A completed scan run id (from recent_scans).; status (optional) — Which findings to list.; category (optional) — Only findings in this category.; limit (optional) — Maximum findings to return.
- Returns
- Counts plus each finding's check, page, evidence and fix.
start_scanScanSpends credits
Start the scan priced by plan_scan. This spends credits from the project owner's balance and cannot be undone: only call it after the user approved the plan_scan price. Pass the planHash from plan_scan; if the price or prompts changed since then the call is refused with PLAN_HASH_MISMATCH and nothing is spent. Supply an idempotencyKey (e.g. a UUID): retrying with the same key never starts a second scan. Follow the run with scan_status.
- Inputs
- planHash (required); mode (required) — crawl_only: site audit only (cheapest). site_icp: site audit plus ICP inference. full: also measures AI answers to the project's monitored prompts (costs the most).; maxPages (optional) — Crawl tier: pages to audit (25, 50, 100, 150, 200 or 250). More pages cost more.; idempotencyKey (required) — Unique key for this intended scan. Reuse it to retry safely.
- Returns
- The new run id.
- Errors
- PLAN_HASH_MISMATCH if the price changed (nothing spent); IDEMPOTENCY_CONFLICT if a key is reused for a different plan; INSUFFICIENT_CREDITS.
track_recommendationProveChanges shared data
Turn one recommendation from a completed scan into a tracked action (state new) the whole workspace can see. Take runId, artifactId and index from the recommendations tool. Confirm with the user first. Reusing the same idempotencyKey is a safe retry.
- Inputs
- runId (required) — The completed run the recommendation came from.; artifactId (required) — recommendationsArtifactId from the recommendations tool.; index (required) — The recommendation's index from the recommendations tool.; idempotencyKey (required) — Unique key for this write (e.g. a UUID). Reuse it to retry safely.
- Returns
- A tracked action in state “new”.
update_recommendationProveChanges shared data
Change a tracked action's state: accepted, implementing, implemented or dismissed, with optional notes. implemented needs a change recorded with record_change first; implemented and dismissed are final. Confirm with the user first. Reusing the same idempotencyKey is a safe retry.
- Inputs
- actionId (required) — The action id (from recommendation_actions or track_recommendation).; toState (required) — The new state.; notes (optional) — Optional note stored with the transition.; idempotencyKey (required) — Unique key for this write (e.g. a UUID). Reuse it to retry safely.
- Returns
- The updated action. Implemented and dismissed are final.
- Errors
- Implemented needs a change recorded first.
whoamiUnderstandRead-only
Return the signed-in heyEO user, the project workflow tools act on, and the user's role in it.
- Inputs
- None.
- Returns
- Your user, the selected project and your workspace role.