# Epovest recipes for agents

Task recipes for an AI assistant helping a person use Epovest. Each recipe is a goal,
the tools to reach it in order, and what to tell the person. The full tool and endpoint
reference is the API doc: https://epovest.com/docs/api.md.

Epovest is prepaid and the person pays in the app; an agent never buys credits. An agent
creates, starts, reads and pauses trackers with the person's API key (https://app.epovest.com/account/api-keys), and
hands back to the app (https://app.epovest.com) for anything involving money or account settings.

## Recipe: connect Epovest to your client

Goal: let the person drive Epovest from the assistant they already use. How depends on the
client.

- Chat connectors that speak OAuth (for example ChatGPT and claude.ai on the web): add
  Epovest as a custom MCP connector with the server URL https://mcp.epovest.com/mcp. The connector finds
  the sign-in on its own; the person signs in to Epovest and approves the access, once. No
  key to paste. The person reviews and revokes connected apps any time in the app
  (https://app.epovest.com).
- CLIs, desktop apps and frameworks that take a header (for example Gemini CLI, Claude
  Desktop config, or your own code): use the same URL https://mcp.epovest.com/mcp with an API key in the
  header, `Authorization: Bearer epo_...`. The person creates the key in the app
  (https://app.epovest.com/account/api-keys).

Both paths reach the same tools and act for the same account. Pick OAuth when the client
offers a one-click connector; use the header key otherwise.

## Recipe: set up reputation tracking for a business

Goal: start measuring how the AI engines answer about a business, its brand and the names
it competes with.

1. Gather from the person, in their own words: the business name, the names it competes
   with, and two or three questions a customer would actually ask an AI (for example,
   "Which accountant should I hire in Lyon?"). Phrase the prompts the way a customer asks,
   not as a search query.
2. Call `create_tracker`:
   - `title`: a short label the person will recognize.
   - `prompts`: the customer questions, verbatim.
   - `engines`: the engines the person cares about; all four by default (`chatgpt`,
     `claude`, `gemini`, `perplexity`).
   - `frequency`: `weekly` is a sensible default; `monthly` costs less, `daily` reacts
     faster.
   - `resolution`: `hd` to start; raise it (`full_hd`, `4k`, `8k`) to sharpen the rates,
     since the answers are stochastic.
   - `keywords`: the business name with `favorite: true`, plus each competitor name.
   - `analysts`: `keyword_presence` and `share_of_voice` are free and deterministic; add
     `sentiment` only if the person wants tone, and tell them it is billed per analyzed
     answer.
   The tracker is created in draft: it measures nothing yet.
3. Call `start_tracker` with the returned `tracker_id`.
   - If it answers `insufficient_credits`, the balance does not cover one survey. Tell the
     person the cost per survey it returns (`cost_per_survey_minor`, in minor units) and
     send them to add credits in the app (https://app.epovest.com). Do not try to pay: an agent
     cannot. Retry `start_tracker` once they have topped up.
   - If it answers `data_access_expired`, the reading window has lapsed; the person tops up
     in the app and you retry.
4. Tell the person: the first results land within 24 to 48 hours, then build up week over
   week. Set the expectation plainly: Epovest measures whether and how often they are
   cited; it does not make them cited.

## Recipe: read and explain the results

Goal: turn a tracker into a plain answer for the person.

1. Call `list_trackers` to find the `tracker_id` if you do not have it.
2. Call `get_results` with the `tracker_id`. Each row is one analyst, keyword, engine and
   survey period:
   - `keyword_presence` rows carry `citation_rate` (how often the name shows up) and
     `weighted_score`.
   - `share_of_voice` rows carry `share_of_voice` (the name's share against the other names
     tracked).
   - `sentiment` rows carry positive, neutral and negative counts.
   Narrow the read with the `analyst` or `engine` filter.
3. To show evidence, call `get_responses` with the `tracker_id` and one `engine`. Each
   answer is the real engine text with its cited sources and the keyword mentions, so the
   person can check a number for themselves. Add `include_raw` only when you need the full
   payload; it is heavy.
4. When you explain: read trends, not a single survey (the answers are stochastic; a higher
   resolution sharpens them). Compare `citation_rate` across engines and `share_of_voice`
   against competitors. Point to a cited source when the person asks why a number moved.
5. When the person wants to track another name they keep seeing in the answers, or drop
   one, call `update_tracker` with the new `keywords` list: it applies in place and the
   series of the other keywords continues. Only the fields you send change; a sent list
   replaces the previous one, so carry over the keywords that stay.
6. When the tracker has discovery on, call `list_keyword_discoveries` once in a while:
   it lists the domains the engines keep citing that no keyword covers. Relay them to the
   person; on their yes, `accept_keyword_discovery` starts tracking one, and
   `dismiss_keyword_discovery` retires a suggestion they do not care about.

## Recipe: keep the balance funded

Goal: unblock a refused start, or top up before the balance runs dry.

1. Call `get_credits`. Compare `available_minor` with the `cost_per_survey_minor` of the
   trackers to run (`list_trackers` carries it, with a `monthly_estimate_minor`). `held_minor`
   is not missing money: it is reserved by surveys in progress and settles when they
   complete.
2. Call `topup_credits` with the amount. Two ways in, and the person's own words come first:
   - They named an amount ("top me up 50"): pass `amount`, in major units, exactly as they
     said it. 50 means 50.00. Never convert it in your head.
   - They left it to you: suggest an amount that covers the coming period, for instance a
     few months of `monthly_estimate_minor`, and pass `amount_minor` (the cost grid is in
     minor units too, so nothing gets converted). Say what you picked and why.

   Send one of the two, not both. The minimum top-up is 10.00.
3. Hand the returned `payment_url` to the person: the payment happens on that hosted page,
   never in this conversation, and nothing is charged until they approve it there. The
   response echoes `amount` and `currency`: confirm those to them before they click.
4. Once paid, everything follows on its own: the balance updates, paused trackers resume and
   the data-access window reopens. Call `get_credits` again to confirm.

`get_credits` and `topup_credits` keep answering once the data-access window has expired:
they are the way back in.

## What stays in the app

An agent does not pay, add a payment method, set up auto-reload, manage members or edit
account settings; send the person to the app (https://app.epovest.com) for those. Everything about
a tracker lives in the tools: create, update, start, pause, read, and prepare top-ups the
person approves. Mind the versioning boundary of `update_tracker`: changing what is
collected (prompts, engines, frequency, resolution) on a tracker that has measured opens a
new version, while keywords, analysts and the title change in place. Prices and the cost
grid are published at https://epovest.com/en/pricing.