@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/core.mjs

@@ -1,244 +1,244 @@
-/**
- * Tool family: core - orientation plus the CRM essentials.
- *
- * These are the original ten kmhub-mcp tools (server 1.2.0), moved here verbatim
- * when the tool set was split into families. Tool names, descriptions, zod schemas,
- * call paths and registration order are all unchanged, so a client that was already
- * connected sees exactly the same ten tools it saw before the split.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'core';
-
-/**
- * Order preserved from the original tools.mjs TOOL_NAMES export, so the health
- * endpoint and the startup log keep printing the same list in the same order.
- */
-export const TOOLS = [
-  'km_me',
-  'km_workspaces',
-  'km_waiting',
-  'km_list_clients',
-  'km_create_lead',
-  'km_list_deals',
-  'km_list_events',
-  'km_list_bookings',
-  'km_create_inquiry',
-  'km_create_booking',
-  'km_create_outreach_draft',
-];
-
-// Orientation and the CRM floor belong in every profile: you always need to know
-// whose workspace this is and what is waiting, whatever else you loaded.
-export const PROFILES = ['*'];
-
-/**
- * @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 }} helpers shared response helpers from ../tools.mjs
- */
-export function register(server, call, { out }) {
-  server.tool(
-    'km_me',
-    'Which KM Hub workspace this connection actually points at: its id, the business name on it, and the plan it is on. ' +
-      'Call it once at the start of a session so you know whose business you are speaking about, and call it again the moment anything looks wrong - an empty client list, a diary with nothing in it, figures that do not match what the user is describing - because the commonest cause of all three is a key pointing at a different workspace than the one they mean. ' +
-      'It does not tell you which human is at the keyboard, it does not list the users on the account, and the plan it reports is the subscription, not how much of this month\'s allowance is left. ' +
-      'It is cheap, it reads, and it changes nothing.',
-    {},
-    async () => out(await call('GET', '/me')),
-  );
-
-  server.tool(
-    'km_workspaces',
-    'Every KM Hub workspace the person at this keyboard belongs to, which single one this connector actually opens, and how to reach the others. ' +
-      'Call it the moment someone talks about a second brand, expects data that is not here, says they switched workspace in the web app, or asks why the numbers look like the wrong business. ' +
-      'The thing it exists to explain: an API key is welded to ONE workspace, so switching brand in the KM Hub web app does not move this connection and never will - the key carries the workspace, not the browser session. Someone can restart Claude all day and still be in the same brand. ' +
-      'It hands out no access and no keys: names and ids only. Reaching another workspace means installing a second connector with a key from that workspace, which the note in the response explains. ' +
-      'It is cheap, it reads, and it changes nothing.',
-    {},
-    async () => out(await call('GET', '/workspaces')),
-  );
-
-  server.tool(
-    'km_waiting',
-    'Raw gate counts and nothing else: how many approvals, new enquiries, open tasks, unpaid invoices and unsigned contracts are sitting in the workspace right now. It is a gauge, not an answer. ' +
-      'Do NOT reach for this on the broad question. If the user says "what needs me today", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session with no specific task, km_briefing is the tool: it returns these same counts AND the actual items behind them, in one list ranked in the order a person should deal with them, each with the reason it is there. Answering the broad question from a set of counts means guessing which of the numbers mattered, which is exactly the guess km_briefing exists to remove. ' +
-      'Reach for km_waiting only when you genuinely want the bare numbers on their own: to say whether anything has changed since earlier in the same conversation, or when km_briefing has told you it is not available on this workspace. ' +
-      'A count tells you something is waiting. It never tells you which one is worth doing first, and it carries no client, no amount, no date and no id, so nothing here can be opened or acted on without a second call. Read only.',
-    {},
-    async () => out(await call('GET', '/waiting')),
-  );
-
-  server.tool(
-    'km_list_clients',
-    'The most recently ADDED clients and leads, newest first. This is a recency window, NOT a search. ' +
-      'It walks back from the newest record and stops, so a contact added a year ago will not appear whatever you set limit to, and even at the maximum of 100 it shows the newest 100 and nothing behind them. ' +
-      'That means it CANNOT answer "do I have X", "find me the person at Y" or "what is that magician called", and treating a miss here as proof somebody is not in the workspace is the easiest way to tell a user something false about their own business. km_find_contact is the tool for finding a named person, a company or part of an email, and it searches all of them rather than the newest few. ' +
-      'Reach for km_list_clients only for the genuinely recency-shaped question: who has come in lately, what do the last few enquiries look like, has anything landed since we spoke. ' +
-      'It returns the record as it stands, not the history behind it: km_get_client opens one in full. Read only.',
-    { limit: z.number().int().min(1).max(100).optional() },
-    async ({ limit }) => out(await call('GET', `/clients?limit=${limit ?? 25}`)),
-  );
-
-  server.tool(
-    'km_create_lead',
-    'Put a person on file as a contact with nothing attached to them: no enquiry, no deal, no date, no money. ' +
-      'Reach for it when the user has met somebody and wants them kept - a card from a convention, a name off a phone call - and there is nothing being sold yet. ' +
-      'Search with km_find_contact FIRST. This tool will happily create a second Sarah Jones alongside the one already there, and a split contact is worse than no contact: half her history sits on a record nobody opens. ' +
-      'It is the wrong tool when there is actually something to sell. If the person is asking about a date, use km_create_inquiry, which creates the contact AND opens the pipeline deal behind it. If the gig is already agreed, use km_create_booking. ' +
-      'Every field is optional, but a contact with no email and no phone can never be written to, so ask for one rather than saving a bare name. ' +
-      'This WRITES: it needs the API key to carry the write scope, and it lands in the AI activity log where the owner can see and undo it.',
-    {
-      first_name: z.string().optional(),
-      last_name: z.string().optional(),
-      company: z.string().optional(),
-      email: z.string().optional(),
-      phone: z.string().optional(),
-      notes: z.string().optional(),
-    },
-    async (args) => out(await call('POST', '/clients', args)),
-  );
-
-  server.tool(
-    'km_list_bookings',
-    'The real jobs: the bookings on this business, each with its client, its date, its venue and the money on it. ' +
-      'Reach for it for the book of business rather than for the diary - what has been booked lately, what is still only pending a confirmation, every gig inside a date range so you can see the shape of a season, what this business has actually done before. ' +
-      'from and to filter on the EVENT date, not on when the booking was taken, so from today forward is the work ahead and to yesterday is the history. Use status to separate the confirmed work from what is still pending. ' +
-      'It caps at 100 rows and does not report the true total, so a busy year needs a narrower window rather than a bigger limit, and if you asked for 100 and got 100, say the picture is partial instead of presenting a slice as the whole book. ' +
-      'It tells you what is BOOKED. It says nothing about whether a new date could be sold, because a free-looking day can still be blocked, out of area or already pencilled in by a live lead: km_check_availability is the only honest answer to that question. km_get_booking opens one booking in full, where that tool is loaded. Read only.',
-    {
-      limit: z.number().int().min(1).max(100).optional(),
-      status: z.string().optional().describe('e.g. confirmed, pending'),
-      from: z.string().optional().describe('Earliest event date, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest event date, YYYY-MM-DD.'),
-    },
-    async ({ limit, status, from, to }) => {
-      const q = new URLSearchParams();
-      q.set('limit', String(limit ?? 25));
-      if (status) q.set('status', status);
-      if (from) q.set('from', from);
-      if (to) q.set('to', to);
-      return out(await call('GET', `/bookings?${q.toString()}`));
-    },
-  );
-
-  server.tool(
-    'km_list_deals',
-    'The pipeline: the live opportunities in this workspace and how far each one has got, newest first. ' +
-      'Reach for it for the shape of the funnel - what is open, what is stuck in quoting, what has been won, what was lost - and to get the deal_id that km_get_deal, km_create_outreach_draft and a play run all need before they can attach anything to the right opportunity. ' +
-      'stage narrows to one column of the board. status is the coarse open, won, lost, abandoned split. status lost, then km_get_deal on the big ones, is how you read WHY work was lost, which is almost always worth more than the count: a large deal lost on timing is a live target, a large deal lost on price is evidence about the rate. ' +
-      'It caps at 100 rows and does not report the true total, so if you asked for 100 and got 100, say the pipeline you are describing is partial. ' +
-      'It cannot search by a client\'s name: find the person with km_find_contact first, then work from their record. Read only.',
-    {
-      limit: z.number().int().min(1).max(100).optional(),
-      stage: z
-        .enum([
-          'inbound',
-          'qualifying',
-          'quoting',
-          'proposal_sent',
-          'booked',
-          'in_progress',
-          'completed',
-          'lost',
-          'abandoned',
-        ])
-        .optional(),
-      status: z.enum(['open', 'won', 'lost', 'abandoned']).optional(),
-    },
-    async ({ limit, stage, status }) => {
-      const q = new URLSearchParams();
-      q.set('limit', String(limit ?? 25));
-      if (stage) q.set('stage', stage);
-      if (status) q.set('status', status);
-      return out(await call('GET', `/deals?${q.toString()}`));
-    },
-  );
-
-  server.tool(
-    'km_list_events',
-    'The raw contents of the KM Hub calendar over a date window, in start order: the gigs and everything else that has been put in the diary alongside them. ' +
-      'Always set from and to. With no window it returns whatever is most recent, which is almost never the question anybody asked. ' +
-      'Reach for it when the user wants the literal contents of a range: what is in September, is there anything at all on that weekend, how full does next month look. ' +
-      'For the ordinary "what have I got on" question, km_my_schedule is the better answer wherever it is loaded, because it groups the days and names the client, venue, times and fee on each gig rather than handing back a flat list. For whether ONE date can be sold, km_check_availability is the only honest source: this tool shows what already exists, and an empty-looking day is not the same as an available one. ' +
-      'Read only: it never adds, moves or cancels anything in the diary.',
-    {
-      from: z.string().optional().describe('Earliest start date, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest start date, YYYY-MM-DD.'),
-      limit: z.number().int().min(1).max(200).optional(),
-    },
-    async ({ from, to, limit }) => {
-      const q = new URLSearchParams();
-      q.set('limit', String(limit ?? 50));
-      if (from) q.set('from', from);
-      if (to) q.set('to', to);
-      return out(await call('GET', `/events?${q.toString()}`));
-    },
-  );
-
-  server.tool(
-    'km_create_outreach_draft',
-    'Queue an outreach message as a DRAFT in KM Hub. This tool NEVER sends anything - the draft lands in the Approval Queue and a human approves it before any send happens. Audited in the AI activity log.',
-    {
-      body: z.string().describe('The message text (required).'),
-      subject: z.string().optional().describe('Subject line (email channel).'),
-      channel: z.enum(['email', 'linkedin', 'ig', 'sms_whatsapp']).optional().describe('Default email.'),
-      deal_id: z.string().optional().describe('UUID of the deal this draft belongs to (see km_list_deals).'),
-      contact_id: z.string().optional().describe('UUID of the client/contact (see km_find_contact).'),
-    },
-    async (args) => out(await call('POST', '/outreach-drafts', args)),
-  );
-
-  server.tool(
-    'km_create_inquiry',
-    'Log a new inquiry (lead + enquiry) in KM Hub - creates the client if needed and opens a pipeline deal. Audited and undoable from the AI activity log.',
-    {
-      client_name: z.string().describe('Full name of the person enquiring.'),
-      client_email: z.string().optional(),
-      client_phone: z.string().optional(),
-      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday.'),
-      event_date: z.string().optional().describe('YYYY-MM-DD.'),
-      event_start_time: z.string().optional().describe('HH:MM 24h.'),
-      event_end_time: z.string().optional().describe('HH:MM 24h.'),
-      venue_name: z.string().optional(),
-      guest_count: z.number().optional(),
-      budget_cents: z.number().optional().describe('Budget in CENTS.'),
-      notes: z.string().optional(),
-    },
-    async (args) => out(await call('POST', '/inquiries', args)),
-  );
-
-  server.tool(
-    'km_create_booking',
-    'Create a REAL confirmed booking on the KM Hub calendar - creates the client if needed and opens a pipeline deal at booked/won. Requires an event_date. Only use when the gig is definitely booked; otherwise use km_create_inquiry.',
-    {
-      client_name: z.string().describe('Full name of the client.'),
-      client_email: z.string().optional(),
-      client_phone: z.string().optional(),
-      title: z.string().optional().describe('Booking title shown on the calendar.'),
-      event_type: z.string().optional(),
-      event_date: z.string().describe('YYYY-MM-DD (required for a real booking).'),
-      event_start_time: z.string().optional().describe('HH:MM 24h.'),
-      event_end_time: z.string().optional().describe('HH:MM 24h.'),
-      venue_name: z.string().optional(),
-      guest_count: z.number().optional(),
-      total_cents: z.number().optional().describe('Total in CENTS.'),
-      status: z
-        .enum(['pending', 'confirmed'])
-        .optional()
-        .describe('Default pending (owner reviews); confirmed puts it straight on the calendar.'),
-      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) => out(await call('POST', '/bookings', args)),
-  );
-}
+/**
+ * Tool family: core - orientation plus the CRM essentials.
+ *
+ * These are the original ten kmhub-mcp tools (server 1.2.0), moved here verbatim
+ * when the tool set was split into families. Tool names, descriptions, zod schemas,
+ * call paths and registration order are all unchanged, so a client that was already
+ * connected sees exactly the same ten tools it saw before the split.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'core';
+
+/**
+ * Order preserved from the original tools.mjs TOOL_NAMES export, so the health
+ * endpoint and the startup log keep printing the same list in the same order.
+ */
+export const TOOLS = [
+  'km_me',
+  'km_workspaces',
+  'km_waiting',
+  'km_list_clients',
+  'km_create_lead',
+  'km_list_deals',
+  'km_list_events',
+  'km_list_bookings',
+  'km_create_inquiry',
+  'km_create_booking',
+  'km_create_outreach_draft',
+];
+
+// Orientation and the CRM floor belong in every profile: you always need to know
+// whose workspace this is and what is waiting, whatever else you loaded.
+export const PROFILES = ['*'];
+
+/**
+ * @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 }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out }) {
+  server.tool(
+    'km_me',
+    'Which KM Hub workspace this connection actually points at: its id, the business name on it, and the plan it is on. ' +
+      'Call it once at the start of a session so you know whose business you are speaking about, and call it again the moment anything looks wrong - an empty client list, a diary with nothing in it, figures that do not match what the user is describing - because the commonest cause of all three is a key pointing at a different workspace than the one they mean. ' +
+      'It does not tell you which human is at the keyboard, it does not list the users on the account, and the plan it reports is the subscription, not how much of this month\'s allowance is left. ' +
+      'It is cheap, it reads, and it changes nothing.',
+    {},
+    async () => out(await call('GET', '/me')),
+  );
+
+  server.tool(
+    'km_workspaces',
+    'Every KM Hub workspace the person at this keyboard belongs to, which single one this connector actually opens, and how to reach the others. ' +
+      'Call it the moment someone talks about a second brand, expects data that is not here, says they switched workspace in the web app, or asks why the numbers look like the wrong business. ' +
+      'The thing it exists to explain: an API key is welded to ONE workspace, so switching brand in the KM Hub web app does not move this connection and never will - the key carries the workspace, not the browser session. Someone can restart Claude all day and still be in the same brand. ' +
+      'It hands out no access and no keys: names and ids only. Reaching another workspace means installing a second connector with a key from that workspace, which the note in the response explains. ' +
+      'It is cheap, it reads, and it changes nothing.',
+    {},
+    async () => out(await call('GET', '/workspaces')),
+  );
+
+  server.tool(
+    'km_waiting',
+    'Raw gate counts and nothing else: how many approvals, new enquiries, open tasks, unpaid invoices and unsigned contracts are sitting in the workspace right now. It is a gauge, not an answer. ' +
+      'Do NOT reach for this on the broad question. If the user says "what needs me today", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session with no specific task, km_briefing is the tool: it returns these same counts AND the actual items behind them, in one list ranked in the order a person should deal with them, each with the reason it is there. Answering the broad question from a set of counts means guessing which of the numbers mattered, which is exactly the guess km_briefing exists to remove. ' +
+      'Reach for km_waiting only when you genuinely want the bare numbers on their own: to say whether anything has changed since earlier in the same conversation, or when km_briefing has told you it is not available on this workspace. ' +
+      'A count tells you something is waiting. It never tells you which one is worth doing first, and it carries no client, no amount, no date and no id, so nothing here can be opened or acted on without a second call. Read only.',
+    {},
+    async () => out(await call('GET', '/waiting')),
+  );
+
+  server.tool(
+    'km_list_clients',
+    'The most recently ADDED clients and leads, newest first. This is a recency window, NOT a search. ' +
+      'It walks back from the newest record and stops, so a contact added a year ago will not appear whatever you set limit to, and even at the maximum of 100 it shows the newest 100 and nothing behind them. ' +
+      'That means it CANNOT answer "do I have X", "find me the person at Y" or "what is that magician called", and treating a miss here as proof somebody is not in the workspace is the easiest way to tell a user something false about their own business. km_find_contact is the tool for finding a named person, a company or part of an email, and it searches all of them rather than the newest few. ' +
+      'Reach for km_list_clients only for the genuinely recency-shaped question: who has come in lately, what do the last few enquiries look like, has anything landed since we spoke. ' +
+      'It returns the record as it stands, not the history behind it: km_get_client opens one in full. Read only.',
+    { limit: z.number().int().min(1).max(100).optional() },
+    async ({ limit }) => out(await call('GET', `/clients?limit=${limit ?? 25}`)),
+  );
+
+  server.tool(
+    'km_create_lead',
+    'Put a person on file as a contact with nothing attached to them: no enquiry, no deal, no date, no money. ' +
+      'Reach for it when the user has met somebody and wants them kept - a card from a convention, a name off a phone call - and there is nothing being sold yet. ' +
+      'Search with km_find_contact FIRST. This tool will happily create a second Sarah Jones alongside the one already there, and a split contact is worse than no contact: half her history sits on a record nobody opens. ' +
+      'It is the wrong tool when there is actually something to sell. If the person is asking about a date, use km_create_inquiry, which creates the contact AND opens the pipeline deal behind it. If the gig is already agreed, use km_create_booking. ' +
+      'Every field is optional, but a contact with no email and no phone can never be written to, so ask for one rather than saving a bare name. ' +
+      'This WRITES: it needs the API key to carry the write scope, and it lands in the AI activity log where the owner can see and undo it.',
+    {
+      first_name: z.string().optional(),
+      last_name: z.string().optional(),
+      company: z.string().optional(),
+      email: z.string().optional(),
+      phone: z.string().optional(),
+      notes: z.string().optional(),
+    },
+    async (args) => out(await call('POST', '/clients', args)),
+  );
+
+  server.tool(
+    'km_list_bookings',
+    'The real jobs: the bookings on this business, each with its client, its date, its venue and the money on it. ' +
+      'Reach for it for the book of business rather than for the diary - what has been booked lately, what is still only pending a confirmation, every gig inside a date range so you can see the shape of a season, what this business has actually done before. ' +
+      'from and to filter on the EVENT date, not on when the booking was taken, so from today forward is the work ahead and to yesterday is the history. Use status to separate the confirmed work from what is still pending. ' +
+      'It caps at 100 rows and does not report the true total, so a busy year needs a narrower window rather than a bigger limit, and if you asked for 100 and got 100, say the picture is partial instead of presenting a slice as the whole book. ' +
+      'It tells you what is BOOKED. It says nothing about whether a new date could be sold, because a free-looking day can still be blocked, out of area or already pencilled in by a live lead: km_check_availability is the only honest answer to that question. km_get_booking opens one booking in full, where that tool is loaded. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional(),
+      status: z.string().optional().describe('e.g. confirmed, pending'),
+      from: z.string().optional().describe('Earliest event date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest event date, YYYY-MM-DD.'),
+    },
+    async ({ limit, status, from, to }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 25));
+      if (status) q.set('status', status);
+      if (from) q.set('from', from);
+      if (to) q.set('to', to);
+      return out(await call('GET', `/bookings?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_list_deals',
+    'The pipeline: the live opportunities in this workspace and how far each one has got, newest first. ' +
+      'Reach for it for the shape of the funnel - what is open, what is stuck in quoting, what has been won, what was lost - and to get the deal_id that km_get_deal, km_create_outreach_draft and a play run all need before they can attach anything to the right opportunity. ' +
+      'stage narrows to one column of the board. status is the coarse open, won, lost, abandoned split. status lost, then km_get_deal on the big ones, is how you read WHY work was lost, which is almost always worth more than the count: a large deal lost on timing is a live target, a large deal lost on price is evidence about the rate. ' +
+      'It caps at 100 rows and does not report the true total, so if you asked for 100 and got 100, say the pipeline you are describing is partial. ' +
+      'It cannot search by a client\'s name: find the person with km_find_contact first, then work from their record. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional(),
+      stage: z
+        .enum([
+          'inbound',
+          'qualifying',
+          'quoting',
+          'proposal_sent',
+          'booked',
+          'in_progress',
+          'completed',
+          'lost',
+          'abandoned',
+        ])
+        .optional(),
+      status: z.enum(['open', 'won', 'lost', 'abandoned']).optional(),
+    },
+    async ({ limit, stage, status }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 25));
+      if (stage) q.set('stage', stage);
+      if (status) q.set('status', status);
+      return out(await call('GET', `/deals?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_list_events',
+    'The raw contents of the KM Hub calendar over a date window, in start order: the gigs and everything else that has been put in the diary alongside them. ' +
+      'Always set from and to. With no window it returns whatever is most recent, which is almost never the question anybody asked. ' +
+      'Reach for it when the user wants the literal contents of a range: what is in September, is there anything at all on that weekend, how full does next month look. ' +
+      'For the ordinary "what have I got on" question, km_my_schedule is the better answer wherever it is loaded, because it groups the days and names the client, venue, times and fee on each gig rather than handing back a flat list. For whether ONE date can be sold, km_check_availability is the only honest source: this tool shows what already exists, and an empty-looking day is not the same as an available one. ' +
+      'Read only: it never adds, moves or cancels anything in the diary.',
+    {
+      from: z.string().optional().describe('Earliest start date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest start date, YYYY-MM-DD.'),
+      limit: z.number().int().min(1).max(200).optional(),
+    },
+    async ({ from, to, limit }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 50));
+      if (from) q.set('from', from);
+      if (to) q.set('to', to);
+      return out(await call('GET', `/events?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_create_outreach_draft',
+    'Queue an outreach message as a DRAFT in KM Hub. This tool NEVER sends anything - the draft lands in the Approval Queue and a human approves it before any send happens. Audited in the AI activity log.',
+    {
+      body: z.string().describe('The message text (required).'),
+      subject: z.string().optional().describe('Subject line (email channel).'),
+      channel: z.enum(['email', 'linkedin', 'ig', 'sms_whatsapp']).optional().describe('Default email.'),
+      deal_id: z.string().optional().describe('UUID of the deal this draft belongs to (see km_list_deals).'),
+      contact_id: z.string().optional().describe('UUID of the client/contact (see km_find_contact).'),
+    },
+    async (args) => out(await call('POST', '/outreach-drafts', args)),
+  );
+
+  server.tool(
+    'km_create_inquiry',
+    'Log a new inquiry (lead + enquiry) in KM Hub - creates the client if needed and opens a pipeline deal. Audited and undoable from the AI activity log.',
+    {
+      client_name: z.string().describe('Full name of the person enquiring.'),
+      client_email: z.string().optional(),
+      client_phone: z.string().optional(),
+      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday.'),
+      event_date: z.string().optional().describe('YYYY-MM-DD.'),
+      event_start_time: z.string().optional().describe('HH:MM 24h.'),
+      event_end_time: z.string().optional().describe('HH:MM 24h.'),
+      venue_name: z.string().optional(),
+      guest_count: z.number().optional(),
+      budget_cents: z.number().optional().describe('Budget in CENTS.'),
+      notes: z.string().optional(),
+    },
+    async (args) => out(await call('POST', '/inquiries', args)),
+  );
+
+  server.tool(
+    'km_create_booking',
+    'Create a REAL confirmed booking on the KM Hub calendar - creates the client if needed and opens a pipeline deal at booked/won. Requires an event_date. Only use when the gig is definitely booked; otherwise use km_create_inquiry.',
+    {
+      client_name: z.string().describe('Full name of the client.'),
+      client_email: z.string().optional(),
+      client_phone: z.string().optional(),
+      title: z.string().optional().describe('Booking title shown on the calendar.'),
+      event_type: z.string().optional(),
+      event_date: z.string().describe('YYYY-MM-DD (required for a real booking).'),
+      event_start_time: z.string().optional().describe('HH:MM 24h.'),
+      event_end_time: z.string().optional().describe('HH:MM 24h.'),
+      venue_name: z.string().optional(),
+      guest_count: z.number().optional(),
+      total_cents: z.number().optional().describe('Total in CENTS.'),
+      status: z
+        .enum(['pending', 'confirmed'])
+        .optional()
+        .describe('Default pending (owner reviews); confirmed puts it straight on the calendar.'),
+      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) => out(await call('POST', '/bookings', args)),
+  );
+}