@kivimedia/kmhub 2.0.0

package/tools/plays.mjs

@@ -0,0 +1,244 @@
+/**
+ * Tool family: plays - the operating intelligence, leased one step at a time.
+ *
+ * Every other family is a door onto the workspace data. This one is the reason a
+ * client would rather have KM Hub in their terminal than a generic assistant with
+ * a CRM connector: the plays are the proven ways this kind of business actually
+ * gets booked, and they are worth more than any single record they touch.
+ *
+ * Which is why none of them live on the client's machine. The protection model,
+ * stated plainly so nobody has to reverse engineer it from the code:
+ *
+ *   - The client's disk holds three things: a URL, an API key, and a rules file
+ *     of pure orientation. No play, no runbook, no criterion, ever.
+ *   - km_play_catalog returns METADATA ONLY: slug, label, and the plain reason a
+ *     human would care. Never the task, never the criterion, never an internal.
+ *   - km_play_run leases ONE bounded step per call. The text arrives in the
+ *     conversation, is used, and is never written to a file by us.
+ *   - Quotas are what stop somebody enumerating the catalog by running everything
+ *     once: a cap per hour, a cap per day, and a cap on how many DIFFERENT plays
+ *     in a rolling day. Repeating a play already seen in that window is free of
+ *     the variety cap, so normal work never hits it and harvesting does.
+ *   - Each issued step carries an HMAC watermark. Be honest about what that is:
+ *     it is forensic attribution, NOT DRM. The task is plaintext in the client's
+ *     own transcript and a determined person can strip the marker. It tells us
+ *     WHERE a leaked task came from. It does not stop the leak.
+ *   - The real kill switch is Phase 1 and it already works: cancel the
+ *     subscription and the entitlement gate answers 402 on every route here, so
+ *     no catalog, no runs, no rules refresh, from the next call onwards.
+ *
+ * Nothing in this family sends anything to anybody. A play that produces a
+ * message still ends at km_create_outreach_draft and the Approval Queue.
+ *
+ * The routes behind it are GET /plays, POST /plays/run and POST /plays/verify.
+ * They own the truth about the body shape, so the two POST handlers pass their
+ * arguments straight through rather than reshaping them here.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'plays';
+
+export const TOOLS = ['km_play_catalog', 'km_play_run', 'km_play_verify'];
+
+// Every profile. A session that can read the calendar but cannot reach the plays
+// is a crippled session: the plays are what make the rest of the tools add up to
+// a way of working rather than a pile of endpoints.
+export const PROFILES = ['*'];
+
+/** The API has not shipped these routes yet (404 / 405 / 501 all mean the same here). */
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not have the plays switched on yet. Nothing is broken and nothing is lost: the workspace is fine and every other tool works as normal. Carry on with the tools you have, and say plainly that the plays are not available on this account rather than inventing a method and calling it one.';
+
+/** Round a retry delay into something a person says out loud. Empty when unknown. */
+function inAbout(seconds) {
+  const s = Number(seconds);
+  if (!Number.isFinite(s) || s <= 0) return '';
+  if (s < 90) return `about ${Math.max(1, Math.round(s))} seconds`;
+  const minutes = Math.round(s / 60);
+  if (minutes < 90) return `about ${minutes} minute${minutes === 1 ? '' : 's'}`;
+  const hours = Math.round(s / 3600);
+  return `about ${hours} hour${hours === 1 ? '' : 's'}`;
+}
+
+/**
+ * Turn a 429 into a sentence a working performer understands.
+ *
+ * The shared out() helper already does this for a 402, and a refusal is the one
+ * moment where a raw status code is least use to anybody. Two different things
+ * answer 429 on this API and they need different words:
+ *
+ *   - `rate_limited` from the API front door: too many calls per minute. A pause
+ *     fixes it.
+ *   - anything else: the play allowance itself. Not a fault, not a charge, and
+ *     not something a retry loop will get around.
+ *
+ * Returns null when the response is not a 429, so callers can carry on normally.
+ */
+function quotaRefusal(r) {
+  if (!r || r.status !== 429) return null;
+  const body = r.data && typeof r.data === 'object' ? r.data : {};
+  const code = String(body.error || body.reason || body.code || '').toLowerCase();
+  const said = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
+  const wait = inAbout(body.retry_after ?? body.retryAfter ?? body.retry_after_seconds);
+  const lines = [];
+
+  if (code.includes('rate_limit')) {
+    lines.push('I am calling KM Hub faster than it allows, so it asked me to slow down. Nothing failed and nothing changed.');
+    lines.push(wait ? `It clears in ${wait}.` : 'It clears on its own in well under a minute.');
+    if (said) lines.push(said);
+    lines.push('Wait it out and try the same call once more. Do not split the work into more calls, which makes it worse.');
+    return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
+  }
+
+  const variety = code.includes('distinct') || code.includes('variety') || code.includes('skill_limit');
+  if (variety) {
+    lines.push(
+      'That is a play this workspace has not opened today, and it has already opened as many different ones as a day allows. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
+    );
+    lines.push(
+      'A play already run today can still be run again as much as it is needed, so if one of those covers what is being asked, use it instead. Otherwise this one is worth doing tomorrow.',
+    );
+  } else {
+    lines.push(
+      'This workspace has run as many plays as its allowance covers for now. Nothing is wrong, nothing was charged, and nothing in the workspace has changed.',
+    );
+    lines.push('The allowance is there so the plays get used on real work rather than pulled through in bulk.');
+  }
+  if (said) lines.push(said);
+  lines.push(wait ? `It frees up again in ${wait}.` : 'It frees up again on its own.');
+  lines.push(
+    'Tell the person that plainly and get on with the work by hand: the clients, the calendar, the drafts and everything else are untouched and still work. Do not retry this in a loop.',
+  );
+  return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
+}
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers
+ */
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_play_catalog',
+    [
+      'The plays: the proven ways a business like this one actually gets booked, kept current by KM Hub and written by people who book work for a living rather than assembled from general marketing advice.',
+      'LOOK HERE FIRST whenever the ask is open ended. "What should I do today", "how do I get more corporate work", "nobody is replying to me", "help me with the fair market", "next month looks empty", "how do I get repeat bookings out of this client": there is very often a play for exactly that, and it will be sharper than anything improvised from what you already know about marketing.',
+      'Free, fast, sends nothing and changes nothing. What comes back is a short list, and each entry is a slug to run it by, its name, and the plain reason a working performer would care about it.',
+      'What it deliberately does NOT contain is the method. The steps are not in here and cannot be worked out from the name, so never describe how a play works or promise what it will produce from the catalog alone. The method arrives one step at a time from km_play_run, and only while the subscription is live.',
+      'Reading the catalog is not doing the work, and reciting the whole list at somebody is not an answer. Name the one or two that actually fit what they said, in their words, and offer to run one.',
+    ].join(' '),
+    {},
+    async () => {
+      const r = await call('GET', '/plays');
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_play_run',
+    [
+      'Run a play: start one, or come back for its next step.',
+      'This is a lease, one step at a time. KM Hub hands back a SINGLE bounded piece of work, aimed at this workspace and this situation, that you can actually finish with the km_* tools already in front of you. Do that step. Tell the person what happened in your own words. Then call this again with the same run_id to get the next one. Keep going until the play says it is finished, then call km_play_verify.',
+      'The step text is working material on loan for this run, not a document to hand over. Do not paste it back to the person verbatim, do not save it into a file, a note, a scratch document or a memory, and do not quote it at length in your reply. They asked for the outcome, not the recipe, and the recipe is the part KM Hub is paid for. Each issued step carries a marker identifying the workspace it was leased to.',
+      'Run the play that fits what was actually asked. There is an allowance on how many plays get pulled in a day and on how many DIFFERENT ones, so do not open plays speculatively, do not work down the catalog to see what each one says, and do not start a second play while the first is unfinished. A play already opened today can be run again as often as it is useful.',
+      'It sends nothing to anybody. A play that produces a message still ends at km_create_outreach_draft, in the Approval Queue, for a human to read and release. If a step asks for something you do not have, say so and ask, rather than filling the gap with a plausible guess.',
+    ].join(' '),
+    {
+      slug: z
+        .string()
+        .describe('Which play to run, exactly as km_play_catalog gave it, for example quiet-week-rescue. Never invent a slug or guess one from a name.'),
+      run_id: z
+        .string()
+        .optional()
+        .describe('Leave this out for the first step. To continue a play you already started, pass back the run id from the previous step and you get the next one.'),
+      context: z
+        .string()
+        .optional()
+        .describe('What the person actually asked for, in their own words, plus anything about right now that the step should take into account. It lets KM Hub aim the step at the real situation instead of the general case.'),
+      step_result: z
+        .string()
+        .optional()
+        .describe('Only when continuing a run: what happened on the step you just finished, in a sentence or two, including anything that did not work. The next step is built on it, so an honest account beats a tidy one.'),
+    },
+    async (args) => {
+      // Slugs are lowercase kebab everywhere in this codebase, and a model that
+      // has read the catalog once and is typing from memory will occasionally
+      // capitalise one. Fixing that here costs nothing and saves a 404.
+      const slug = String(args?.slug || '').trim().toLowerCase();
+      if (!slug) {
+        return text(
+          'I need to know which play to run. km_play_catalog lists the ones this workspace has, with the slug for each.',
+        );
+      }
+      // The route requires an idempotency_key (8-128 of [A-Za-z0-9._:-]) so a
+      // retry cannot double-spend a quota slot. It is minted here, never asked
+      // of the model: a caller-chosen key is a footgun, and a model has no
+      // basis to invent a stable one. Continuing a run reuses a key derived
+      // from the run id so a retried continuation replays instead of counting
+      // twice; a fresh run gets a random one.
+      const runId = String(args?.run_id || '').trim();
+      const idempotency_key = runId
+        ? `run-${runId.replace(/[^A-Za-z0-9._:-]/g, '')}`.slice(0, 128)
+        : crypto.randomUUID().replace(/-/g, '');
+      const r = await call('POST', '/plays/run', { ...args, slug, idempotency_key });
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_play_verify',
+    [
+      'Check whether the play actually worked. Every play has a criterion: the observable thing that should be true now if it did its job. That is a different question from whether you got through the steps, and it is the one that matters.',
+      'Call it when a play reaches its end, or whenever someone asks whether the thing you ran last week did anything. KM Hub gives you the criterion, you check it against what you can genuinely see through the km_* tools, and you report what you found.',
+      'Being honest here is the whole point of the tool. "I ran it, and I cannot confirm yet that it worked" is a real answer, a useful one, and far better than a confident yes that falls apart a week later. Say which part you could confirm, which part you could not, and what would settle it.',
+      'Do not call a play successful because the steps are done. Do not verify a play you did not run. This changes nothing in the workspace, sends nothing to anybody, and cannot make a play have worked.',
+    ].join(' '),
+    {
+      run_id: z
+        .string()
+        .optional()
+        .describe('The run being checked, as returned by km_play_run. Give this whenever you have it: it is what ties the criterion to the work that was actually done.'),
+      slug: z
+        .string()
+        .optional()
+        .describe('The play being checked, as km_play_catalog gave it. Pass it alongside run_id for context. On its own it is not enough: the check is tied to a specific run, so without the run id from km_play_run there is nothing to judge against.'),
+      outcome: z
+        .string()
+        .optional()
+        .describe('What you did and what you can see now, in plain words, so the criterion is judged against reality rather than against intent. Include what did not happen as well as what did.'),
+    },
+    async (args) => {
+      const runId = String(args?.run_id || '').trim();
+      const slug = String(args?.slug || '').trim().toLowerCase();
+      if (!runId) {
+        return text(
+          'I need the run id that km_play_run gave back, because the check is tied to that specific run. ' +
+          'If it is genuinely lost, run the play again rather than guessing whether the old one worked.',
+        );
+      }
+      // The route reads `evidence`; this tool calls it `outcome` because that
+      // is the friendlier word for a model. Map it, or every call 400s.
+      const r = await call('POST', '/plays/verify', {
+        run_id: runId || undefined,
+        slug: slug || undefined,
+        evidence: String(args?.outcome || '').trim() || undefined,
+      });
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      const refused = quotaRefusal(r);
+      if (refused) return refused;
+      return out(r);
+    },
+  );
+}

package/tools/sourcing.mjs

@@ -0,0 +1,220 @@
+/**
+ * Tool family: sourcing - finding new people to work with.
+ *
+ * THIS IS THE ONE FAMILY THAT SPENDS THE CLIENT'S MONEY. Every other family
+ * reads or drafts for free. Three tools here reach paid outside services on KM
+ * Hub's accounts, and the whole design of this file exists to make sure a person
+ * always knows the price before a cent moves:
+ *
+ *   - Every paid tool takes `confirm_spend`. Left out, the tool returns the
+ *     current price and changes nothing. That first call is free, always.
+ *   - The price is not written down here. It comes back live from KM Hub, which
+ *     works it out from what this workspace has actually paid for the same thing.
+ *   - A workspace that has run out of its monthly allowance is refused with the
+ *     same sentence it would see in the browser, not quietly charged.
+ *
+ * Nothing here sends anything to anybody. A scout writes its first message as a
+ * DRAFT into the Approval Queue and a human releases it.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'sourcing';
+
+export const TOOLS = [
+  'km_sourcing_prices',
+  'km_start_lead_scout',
+  'km_list_lead_scouts',
+  'km_lead_scout_status',
+  'km_stop_lead_scout',
+  'km_find_company_contacts',
+  'km_check_email_address',
+];
+
+// Finding new people is outreach work, so this family joins that profile. It is
+// not in `core`: a session that only wants the cheap tools should not be handed
+// the spending ones.
+export const PROFILES = ['outreach'];
+
+/** The API has not shipped these routes yet. Say so kindly rather than erroring. */
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not have lead sourcing switched on yet. Nothing is broken, and every other tool works as normal. Nothing was charged.';
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers
+ */
+export function register(server, call, { out, text, qs }) {
+  // Prices first: the free tool that makes every paid one safe to reach for.
+
+  server.tool(
+    'km_sourcing_prices',
+    'What the paid lead-finding tools cost in this workspace right now. Reading this is free and changes nothing. Reach for it whenever someone asks what finding leads costs, or before you suggest running a scout, so you can tell them the price in their own money rather than guessing. The figures come from what this workspace has actually been charged for the same work, so they get more accurate the more it is used. It will not run anything and it will not charge anything.',
+    {},
+    async () => {
+      const r = await call('GET', '/sourcing/prices');
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  // The scout: the big one, and the only asynchronous tool in this family.
+
+  server.tool(
+    'km_start_lead_scout',
+    [
+      'Send KM Hub off to find new potential clients: it searches for people matching a description, digs out their real email address, checks the address is live, reads up on each business, and writes a first message for each one.',
+      'THIS COSTS REAL MONEY and it is the largest single charge in KM Hub. Never quote a price from memory: it depends on how many leads you ask for and it differs per workspace, so the figure comes back live from the first call. Never start one on your own initiative.',
+      'How to use it: call it FIRST without confirm_spend. Nothing is charged and nothing runs; you get back the current price for this workspace. Tell the person that price in plain words, wait for them to say yes, and only then call it again with confirm_spend set to true.',
+      'Describe who to find in ordinary language, the way the person said it: "wedding planners in Austin who do big corporate parties" works better than a pile of filters. Add the filters only if the person actually named them.',
+      'It does not run while you wait. It runs on KM Hub servers over several minutes to an hour, so start it, tell the person it is off and running, and check on it later with km_lead_scout_status. The session can end in between.',
+      'What it will NOT do: it never emails anybody. Contacts land in the pipeline and each first message is written as a DRAFT in the Approval Queue for a person to read and approve. It refuses to run at all if the workspace has used up its monthly allowance, and it will say so instead of spending.',
+    ].join(' '),
+    {
+      describe: z
+        .string()
+        .optional()
+        .describe('Who to find, in plain English, in the person\'s own words. For example: "owners of boutique hotels in Miami that host weddings". This is the main input - prefer it over the filter lists below.'),
+      target_count: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('How many contacts to aim for. Default 25. More costs more, and only about one person in three turns out to have a reachable email, so a bigger number also takes longer. Capped at 100 from here.'),
+      area: z.string().optional().describe('The town, city or region, if the person named one separately from the description.'),
+      titles: z.array(z.string()).optional().describe('Job titles to look for, only if the person named specific ones. For example ["Owner", "Events Manager"].'),
+      locations: z.array(z.string()).optional().describe('Cities or regions as separate entries, if the person listed several.'),
+      industries: z.array(z.string()).optional().describe('Industries to look in, if the person named them.'),
+      keywords: z.array(z.string()).optional().describe('Extra words that should show up on the person or the business.'),
+      company_sizes: z.array(z.string()).optional().describe('Company head-count bands, only if the person asked for a size. For example ["1,10", "11,50"].'),
+      seniorities: z.array(z.string()).optional().describe('Seniority levels, only if the person asked. For example ["owner", "founder", "director"].'),
+      outreach_context: z
+        .string()
+        .optional()
+        .describe('What the person is offering these leads, in a sentence, so the drafted first message is about something real. For example: "balloon installations for corporate galas in Austin, entrance arches and centrepieces".'),
+      vertical_flavor: z.string().optional().describe('The trade the workspace is in, if it needs to be forced. Normally leave this out and let KM Hub use the workspace setting.'),
+      deep_research: z
+        .boolean()
+        .optional()
+        .describe('Read up on each business before writing to it. On by default. Turning it off makes the run cheaper and faster but the first messages far more generic.'),
+      ai_copywriting: z
+        .boolean()
+        .optional()
+        .describe('Write a first message for each contact, as a draft. On by default. Turn it off to just collect verified contacts with no message written.'),
+      confirm_spend: z
+        .boolean()
+        .optional()
+        .describe('Leave this out on the first call: you get the price back and nothing is charged. Set it to true ONLY after the person has been told the price and has agreed to it.'),
+    },
+    async (args) => {
+      const r = await call('POST', '/sourcing/missions', args);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_lead_scouts',
+    'List the recent lead scouts in this workspace, newest first, with what stage each one is at. Free to call and changes nothing. Reach for it when someone asks whether anything is running, what happened to the search from yesterday, or how the last few went. If one is still going, follow up with km_lead_scout_status for its live progress. It does not start anything and does not charge anything.',
+    {
+      limit: z.number().int().min(1).max(50).optional().describe('How many to list. Default 10.'),
+      status: z
+        .enum(['queued', 'running', 'succeeded', 'failed', 'canceled'])
+        .optional()
+        .describe('Only show scouts in this state. Leave out to see them all.'),
+    },
+    async ({ limit, status }) => {
+      const r = await call('GET', `/sourcing/missions${qs({ limit: limit ?? 10, status })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_lead_scout_status',
+    'Check on one lead scout: what it is doing right now, how many people it has found, verified and written to so far, and its final results once it is done. Free to call and changes nothing. Reach for it after starting a scout, or whenever someone asks how the search is getting on. Report it back as a plain sentence about where it has got to, not as a list of numbers. If it says failed, the error field explains why and the person can start a fresh one. It does not restart anything and does not charge anything.',
+    {
+      mission_id: z.string().describe('The id of the scout, as returned when it was started or by km_list_lead_scouts.'),
+    },
+    async ({ mission_id }) => {
+      const id = String(mission_id || '').trim();
+      if (!id) return text('I need the id of the scout to look it up. km_list_lead_scouts will show you the recent ones.');
+      const r = await call('GET', `/sourcing/missions/${encodeURIComponent(id)}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_stop_lead_scout',
+    'Stop a lead scout that is queued or already running. Reach for it the moment someone says stop, cancel, that is enough, or realises the search was set up wrong. Stopping is the money-saving move and is always safe: the workspace is only charged for the lookups already made, never for the work the scout did not do. Anything it already found stays in the pipeline, and any message it already wrote stays as a draft in the Approval Queue. It cannot stop a scout that has already finished, and it will say so plainly rather than pretending. It does not delete anything.',
+    {
+      mission_id: z.string().describe('The id of the scout to stop, from km_list_lead_scouts or from when it was started.'),
+    },
+    async ({ mission_id }) => {
+      const id = String(mission_id || '').trim();
+      if (!id) return text('I need the id of the scout to stop it. km_list_lead_scouts will show you which ones are still running.');
+      const r = await call('POST', `/sourcing/missions/${encodeURIComponent(id)}/cancel`, {});
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  // The two small paid lookups: one company, or one address.
+
+  server.tool(
+    'km_find_company_contacts',
+    [
+      'Find the decision-makers at ONE named business and get their real email addresses. Use it when the person has a specific company in mind: a venue they want to work with, a business that just opened nearby, a lead in the pipeline with a company name but no contact.',
+      'THIS COSTS REAL MONEY, though only a small fraction of a full scout: it looks up at most five people at that one business.',
+      'How to use it: call it FIRST without confirm_spend. That call is free, changes nothing, and comes back with the price. Tell the person, get a yes, then call again with confirm_spend set to true.',
+      'For finding many people across many companies at once, do not loop this tool. Use km_start_lead_scout instead, which is built for it and cheaper per contact.',
+      'What it will NOT do: it never writes to anyone. It hands back names, titles and addresses, and nothing more. If nobody reachable turns up, nothing is charged for the empty result.',
+    ].join(' '),
+    {
+      company: z.string().optional().describe('The business name, as the person said it. For example "The Grand Ballroom" or "Dazzling Balloons".'),
+      website: z.string().optional().describe('The company website, if known. Helps when the name is a common one. Either company or website is required.'),
+      location: z.string().optional().describe('Town or city, if it helps tell this business apart from others with the same name.'),
+      confirm_spend: z
+        .boolean()
+        .optional()
+        .describe('Leave this out on the first call: you get the price back and nothing is charged. Set it to true ONLY after the person has agreed to the cost.'),
+    },
+    async (args) => {
+      const r = await call('POST', '/sourcing/company-contacts', args);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_check_email_address',
+    [
+      'Check whether one email address is real and safe to write to, before anybody writes to it. Reach for it when someone reads an address off a business card or a website, when a contact in the pipeline looks doubtful, or before a message goes out to an address nobody has ever used.',
+      'This matters more than it sounds: writing to dead addresses is what gets a sender flagged as spam, and once that happens the good messages stop arriving too.',
+      'It COSTS REAL MONEY, but only a small amount for one address, and it charges nothing at all for an address that is obviously mistyped.',
+      'How to use it: call it FIRST without confirm_spend to see the price for free, then again with confirm_spend set to true. For a routine single check, telling the person the amount that came back and going ahead is usually enough.',
+      'It answers one of four ways: safe to write to, will bounce, risky, or could not tell. It also flags shared inboxes like info@ or sales@, which get far weaker replies than a named person.',
+      'What it will NOT do: it checks one address per call, it never writes to the address, and it never adds anybody to anything.',
+    ].join(' '),
+    {
+      email: z.string().describe('The single email address to check.'),
+      confirm_spend: z
+        .boolean()
+        .optional()
+        .describe('Leave this out to see the price first without being charged. Set it to true to actually run the check.'),
+    },
+    async (args) => {
+      const r = await call('POST', '/sourcing/verify-email', args);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+}