@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/sourcing.mjs

@@ -1,268 +1,268 @@
-/**
- * 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"].'),
-      avoid_keywords: z
-        .array(z.string())
-        .optional()
-        .describe('Words that disqualify a lead, matched whole-word against the company name, job title and snippet. For example ["ticketing", "parking", "dean"]. This narrows a search, it cannot be the only filter.'),
-      keep_keywords: z
-        .array(z.string())
-        .optional()
-        .describe('Words that rescue a lead from an avoid word, but only for the avoid words listed in rescuable_avoid_keywords. For example ["events", "homecoming", "graduation"].'),
-      rescuable_avoid_keywords: z
-        .array(z.string())
-        .optional()
-        .describe('Which avoid_keywords a keep_keyword is allowed to override. Use for avoid words that name a DEPARTMENT rather than a job, since those also catch that department\'s event desk - who is usually the buyer. For example ["director of athletics", "chancellor"]. Leave out to make every avoid word absolute.'),
-      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.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
-            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
-            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
-            + 'arguments. A yes for one action never authorises a different one.',
-        ),
-    },
-    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.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
-            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
-            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
-            + 'arguments. A yes for one action never authorises a different one.',
-        ),
-    },
-    async ({ mission_id, confirm_token }) => {
-      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`, { confirm_token });
-      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.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
-            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
-            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
-            + 'arguments. A yes for one action never authorises a different one.',
-        ),
-    },
-    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.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
-            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
-            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
-            + 'arguments. A yes for one action never authorises a different one.',
-        ),
-    },
-    async (args) => {
-      const r = await call('POST', '/sourcing/verify-email', args);
-      if (routeMissing(r)) return text(NOT_SUPPORTED);
-      return out(r);
-    },
-  );
-}
+/**
+ * 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"].'),
+      avoid_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Words that disqualify a lead, matched whole-word against the company name, job title and snippet. For example ["ticketing", "parking", "dean"]. This narrows a search, it cannot be the only filter.'),
+      keep_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Words that rescue a lead from an avoid word, but only for the avoid words listed in rescuable_avoid_keywords. For example ["events", "homecoming", "graduation"].'),
+      rescuable_avoid_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Which avoid_keywords a keep_keyword is allowed to override. Use for avoid words that name a DEPARTMENT rather than a job, since those also catch that department\'s event desk - who is usually the buyer. For example ["director of athletics", "chancellor"]. Leave out to make every avoid word absolute.'),
+      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.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    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.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    async ({ mission_id, confirm_token }) => {
+      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`, { confirm_token });
+      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.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    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.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    async (args) => {
+      const r = await call('POST', '/sourcing/verify-email', args);
+      if (routeMissing(r)) return text(NOT_SUPPORTED);
+      return out(r);
+    },
+  );
+}