Agent guide

Using heyEO from your agent

Connect heyEO to your AI agent and run the whole loop by asking: understand what's wrong, price and run a scan, then check whether your change helped.

On this page

Quickstart

Connect in two minutes.

https://mcp.heyeo.io/mcp
  1. Open Settings → Connectors.
  2. Choose Add custom connector.
  3. Paste the heyEO connector URL.
  4. Sign in with your heyEO account.
https://mcp.heyeo.io/mcp

Your agent signs in as you and sees only the projects you can open in the app. If you have more than one, it will ask which one.

Try this first: “Using heyEO, what should I fix first on my site?”

Instructions advertised by the connector

heyEO measures a website's search and AI-answer visibility and proves whether changes helped. You act as the signed-in heyEO user, on the project selected at sign-in (whoami shows it; select_project switches). Typical loop: recommendations or site_health to find what to fix; track_recommendation; after the user ships the fix, record_change; plan_scan then start_scan to measure; scan_status to follow it; did_it_improve to compare with the baseline. Scans spend credits from the project owner's balance. Always call plan_scan first, show the user the price, and call start_scan only after they approve, with the same planHash and a fresh idempotencyKey. Report results honestly: when did_it_improve finds no measurable change, or a tool warns about a small sample, say so rather than implying progress. If a tool returns AUTH_EXPIRED, ask the user to reconnect heyEO in their client.

App, agent or API?

AppAgentAPI
Best forVisual review, charts, settingsAsking questions, the fix-and-check loopCI jobs and scripts
Signs in withYour heyEO accountYour heyEO accountAn automation token
Doesn't doAnswer questions in your own wordsBilling, team or project settingsConversation or judgement

For scripts, see the API docs.

The evidence loop

One fix, measured from start to finish.

  1. 1recommendationsFind a recommendation worth doing.
  2. 2track_recommendationTrack it so the team can see it.
  3. 3—Ship the fix on your site.
  4. 4record_changeLog the page you changed and when.
  5. 5plan_scanAfter the follow-up date, price a new scan.
  6. 6start_scanApprove the price; the scan starts.
  7. 7scan_statusWait for it to finish.
  8. 8did_it_improveGet the honest before/after.

did_it_improve can return “no measurable change” and may include comparability or sample-size warnings. Those warnings are part of the result and should be repeated rather than smoothed over.

Prefer the screens? The Getting Started guide walks through the same loop in the app — including the fix handoff and the before/after receipt.

Scans and credits

  • Three modes: crawl_only (site pages only), site_icp (site plus customer-profile check) and full (adds AI answers for your monitored prompts).
  • plan_scan is free. It returns the price, line items and a planHash.
  • start_scan only runs at that price. If the price or prompts changed, it returns PLAN_HASH_MISMATCH and nothing is spent.
  • idempotencyKey means repeating a request never starts a second scan. Reusing a key for a different plan returns IDEMPOTENCY_CONFLICT.
  • scan_status with waitSeconds lets your agent wait for a scan instead of asking over and over.
  • Credits come from the project owner's balance. Reading results is free.

“Ask before spending” — paste into your agent's instructions

When using heyEO: always call plan_scan first and show me the price and line items. Never call start_scan until I reply "yes" to that exact price. Before tracking, updating or recording anything, tell me what you'll do and wait for my OK. Always repeat heyEO's warnings word for word.

Tool reference

All 20 tools the heyEO connector offers.

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.

Errors and what to do

Your agent reads these too.

ErrorMeansDo this
AUTH_EXPIREDThe heyEO sign-in expired or was revoked.Reconnect heyEO in your MCP client.
PROJECT_NOT_SELECTEDNo project is selected for this session.Call select_project with one of your project ids.
PROJECT_NOT_FOUNDThe project does not exist or this account cannot open it.Check the id with whoami, or ask a workspace owner for access.
INVALID_INPUTAn argument is missing or malformed.Fix the argument named in the message and call again.
INSUFFICIENT_CREDITSThe project owner's balance cannot cover the scan.The owner adds credits in heyEO, or plan a cheaper scan.
PLAN_HASH_MISMATCHThe price or monitored prompts changed since plan_scan.Run plan_scan again and get approval for the new price. Nothing was spent.
IDEMPOTENCY_CONFLICTThe idempotencyKey was already used for a different scan plan.Use a new idempotencyKey for a new scan.
SCAN_START_UNCERTAINheyEO may or may not have started the scan (timeout or server error).Retry start_scan with the same idempotencyKey, or check recent_scans first.
NO_PROMPTSA full scan was requested but the project has no active monitored prompts.Add prompts in heyEO, or plan a site_icp or crawl_only scan.
RUN_NOT_COMPLETEThe scan has not finished, so its results are not available yet.Follow it with scan_status (waitSeconds lets the call wait), then try again.
POLL_EXHAUSTEDThe scan was still running when the wait ended.Call scan_status again later.
ACCESS_RESTRICTEDThis environment is limited to heyEO operators.Use the production connector, https://mcp.heyeo.io/mcp.
UPSTREAM_REJECTEDheyEO refused the request; the message says why.Follow the message, for example an owner-only action needs the project owner.
UPSTREAM_ERRORheyEO returned an unexpected error.Try again shortly; reads are safe to retry.
TIMEOUTheyEO did not answer in time.Try again shortly; for start_scan, reuse the same idempotencyKey.

Security and permissions

  • Your agent acts as you, signed in with your heyEO account. There's no separate API key.
  • It sees only the projects you can open in the app, and can't do anything you can't do there.
  • Everything it records — tracked tasks, changes, baselines — is recorded as you.
  • Some actions are owner only, such as setting the baseline.
  • You can disconnect heyEO from your agent at any time.

Honest results

“No measurable change” is a real answer. Search and AI answers move slowly and noisily. If the before and after are the same within what the data can show, heyEO says so instead of finding a story.

Small samples are flagged. When AI-visibility figures rest on only a handful of answers (fewer than 20), heyEO warns that small moves are normal variation. Runs that measured different things are marked as partly comparable or not comparable. Ask your agent to repeat these warnings.

Recipes

Weekly SEO check-in

Monday morning, five minutes.

Using heyEO, summarise my latest finished scan: the three most important site issues, my AI mention rate, and anything that changed since my baseline. Repeat any warnings exactly as heyEO gives them.

recent_scansdid_it_improverecommendations

Fix my top 3 and track them

When you have an afternoon for fixes.

Using heyEO, show me the top three recommendations from my latest scan with the pages affected. Ask me which ones to track, then track only those.

recommendationstrack_recommendation

Did last month's changes help?

Once a month.

Using heyEO, list my tracked actions that have a recorded change, then tell me whether things improved since my baseline. If the answer is “no measurable change”, say so and explain the warnings.

recommendation_actionsdid_it_improvecompare_runs

Explain my AI visibility to my boss

Before a team update.

Using heyEO, explain in five plain sentences how AI assistants answered my monitored prompts in the latest scan: how often we were named, who was named instead, and how much the sample size limits what we can say.

ai_visibility

What changed since my baseline?

After any scan.

Using heyEO, compare my latest finished scan with my baseline. Group the changes into new, resolved and changed, and skip anything unchanged.

compare_runs

Price a scan before I commit

Whenever you want fresh data.

Using heyEO, price a full scan of my project and show me the line items. Do not start it until I say yes.

plan_scan

Who's showing up instead of us?

When planning content.

Using heyEO, list the brands AI assistants named for my monitored prompts in the latest scan, most frequent first, and the sites they cited.

ai_visibility

I just shipped a fix — log it

Right after you deploy.

Using heyEO, find my tracked action about this fix, record the change for this URL, and tell me when a follow-up scan can show its effect:

recommendation_actionsrecord_change

With your other tools

Ideas that depend on your agent's other connectors, not on heyEO.

  • Ask your agent to post the weekly check-in summary to your team chat.
  • Ask it to turn tracked recommendations into issues in your project tracker.
  • In a coding agent, ask it to read a recommendation, make the fix in your site's code, then log the change in heyEO.
  • Ask it to draft a monthly update for your boss from did_it_improve, caveats included.