@leadbay/mcp 0.17.1 → 0.17.3

package/dist/http-server.js

@@ -6187,6 +6187,8 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_import_leads",
   "leadbay_import_status",
   "leadbay_list_campaigns",
+  "leadbay_my_lenses",
+  "leadbay_new_lens",
   "leadbay_prepare_outreach",
   "leadbay_pull_followups",
   "leadbay_pull_leads",
@@ -6297,7 +6299,37 @@ WHEN NOT TO USE: to log an outreach action \u2014 use leadbay_report_outreach, w
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
-var leadbay_adjust_audience = `Restrict (or expand) the lens audience by sector / size. Free-text sectors are auto-resolved against the sector taxonomy; ambiguous matches are surfaced to the agent rather than guessed silently. Permission routing is hidden: the default lens auto-clones to a new user lens; an org-level lens defaults to a per-user draft (admins can override with \`save_for_org:true\`). Filter MERGES with existing criteria (unrelated criteria are not dropped).
+var leadbay_adjust_audience = `## WHEN TO USE
+
+Trigger phrases: "narrow the audience to <sector>", "add <sector> to my <name> lens", "remove <sector> from this lens", "only show me companies of <size>", "stop including <sector>", "broaden this lens to also include <sector>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "create a new lens called X" \u2192 \`leadbay_new_lens\`; "make a new audience for Y" \u2192 \`leadbay_new_lens\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`; "focus on a kind of company beyond sector/size (e.g. 'hospitals running their own IT')" \u2192 \`leadbay_refine_prompt\`.
+
+Prefer when: user wants to change an EXISTING lens's sectors/sizes. If the user NAMES a lens ('my Joinery lens'), you MUST pass lensName with that name \u2014 do NOT edit the active lens. To create a brand-new lens use leadbay_new_lens instead.
+
+Examples that SHOULD invoke this tool:
+- "Add fintech to my Joinery lens."
+- "Narrow my audience to manufacturing companies, 50\u2013500 people."
+- "Stop including retail in this lens."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a lens called Joinery for fintech."
+- "Show me my lenses."
+- "Focus on hospitals that run their own IT."
+
+## RENDER (quick)
+
+On \`applied\`: confirm the lens edited (name) + the sectors/sizes added as
+chips. On \`ambiguous_sectors\` / \`ambiguous_lens\` / \`lens_not_found\`: surface
+the candidates and ask the user to pick, then re-call with the id/exact name.
+
+---
+
+Restrict (or expand) the lens audience by sector / size. Free-text sectors are auto-resolved against the sector taxonomy; ambiguous matches are surfaced to the agent rather than guessed silently. Permission routing is hidden: the default lens auto-clones to a new user lens; an org-level lens defaults to a per-user draft (admins can override with \`save_for_org:true\`). Filter MERGES with existing criteria (unrelated criteria are not dropped).
+
+**Targeting a lens \u2014 READ THIS.** By default this edits the user's ACTIVE lens. **If the user names a lens** ("add fintech to my **Joinery** lens", "in my Nordics lens, exclude retail"), you MUST pass \`lensName\` with that name (\`lensName:"Joinery"\`). Do NOT silently edit the active lens when a different one was named \u2014 that corrupts the wrong audience and is a top friction source. The name resolves against the user's lenses (case-insensitive, exact then unique-substring); it is edit-only and does NOT change which lens is active. An unmatched name returns \`status:"lens_not_found"\` with the lens list, and a name matching several returns \`status:"ambiguous_lens"\` with the candidates \u2014 surface them and re-call with the exact \`lensName\` or a \`lensId\`. Use \`leadbay_my_lenses\` if the user first wants to SEE or SWITCH lenses. To CREATE a brand-new lens, use \`leadbay_new_lens\` \u2014 not this tool.
 
 WHEN TO USE: when the user wants to see different kinds of leads (sector / size / etc.).
 
@@ -7511,6 +7543,258 @@ WHEN NOT TO USE: if a token is already preconfigured \u2014 you'll just overwrit
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_my_lenses = `## WHEN TO USE
+
+Trigger phrases: "show me my lenses", "list my lenses", "which audiences do I have", "switch to my <name> lens", "change lens", "rename my <name> lens to <X>", "set the description of my <name> lens", "delete my <name> lens", "remove this lens".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "narrow the audience" \u2192 \`leadbay_adjust_audience\`; "stop showing me <sector>" \u2192 \`leadbay_refine_prompt\`; "more leads on this lens" \u2192 \`leadbay_extend_lens\`; "show me today's leads" \u2192 \`leadbay_pull_leads\`.
+
+Prefer when: user wants to SEE lenses, CHANGE which is active, RENAME one, or DELETE one \u2014 not edit a lens's sector/size criteria
+
+Examples that SHOULD invoke this tool:
+- "Show me my lenses."
+- "Rename my Auto lens to Automotive and add a description."
+- "Delete my old Auto lens."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Narrow the audience to fintech only."
+- "I want more leads on this lens."
+- "Show me today's leads."
+
+## RENDER (quick)
+
+Small markdown table, active lens first: col 1 = \u2B50 prefix when active +
+lens name; col 2 = description (or \`\u2014\`). After a switch lead with
+"Now showing **<name>**."; after a rename lead with the rename confirmation.
+Full algorithm below.
+
+---
+
+List the user's lenses (saved audiences) and, when asked, switch which one is active. A lens shapes the kind of leads delivered each day; this tool is how the user sees their audiences and moves between them \u2014 it does NOT edit a lens's criteria (that's \`leadbay_adjust_audience\`).
+
+**Three modes, one tool:**
+
+- **List (no args)** \u2014 pure read. Returns \`{status:"listed", lenses:[{id, name, description, is_active}], active_lens_id}\`. The active lens is resolved from the user's last-requested lens, so \`is_active\` is authoritative even if a row's flag is stale.
+- **Switch (\`switchToLensId\`)** \u2014 changes the active lens to that id and returns the REFRESHED list. The id MUST be one of the user's lenses; an unknown id returns \`{status:"not_found"}\` with the current list \u2014 surface it and ask the user to pick, do NOT invent an id. Switching to the already-active lens is a harmless no-op.
+- **Edit (\`editLensId\` + \`newName\` and/or \`newDescription\`)** \u2014 rename and/or set the description of a lens in one call, returns the REFRESHED list. Provide either or both; pass \`newDescription:""\` to clear a description. Same not_found handling. Use the \`id\` from the list for the lens the user named.
+- **Delete (\`deleteLensId\`)** \u2014 DESTRUCTIVE and confirm-gated. Without \`confirm:true\` it returns \`status:"delete_preview"\` with \`will_delete\` and removes NOTHING \u2014 show it, get the user's explicit yes, then re-call with \`confirm:true\`. The DEFAULT lens cannot be deleted (\`status:"cannot_delete_default"\`). Deleting the active lens leaves no active lens until the next switch/pull resolves one.
+
+**Lens ids are strings** (e.g. \`"40005"\`) \u2014 pass the \`id\` value straight from the list when switching/renaming/deleting; it is fine to pass it as the string it came as.
+
+**When the user is vague** ("switch lens" with no target), list first, then offer the lenses as a quick choice via \`ask_user_input_v0\` rather than guessing.
+
+WHEN TO USE: when the user wants to see their lenses or switch the active one. Canonical phrasings: "show me my lenses", "which audiences do I have", "switch to my <name> lens".
+
+WHEN NOT TO USE: to change a lens's audience criteria \u2014 that's \`leadbay_adjust_audience\`. Not for refining beyond firmographics (\`leadbay_refine_prompt\`), not for topping up the same lens (\`leadbay_extend_lens\`), not for the daily pull (\`leadbay_pull_leads\`).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
+---
+
+## RENDERING \u2014 lenses table, active-first
+
+Markdown table with TWO columns. Sort **active lens first**, then by \`name\`
+ascending. **No score bar** \u2014 the \`\u25B0\u2756\u25B1\` glyph identity belongs to lead
+discovery, not lenses.
+
+**Column 1 \u2014 Lens**
+- Prefix \`\u2B50 \` when \`is_active\` is true; otherwise no prefix.
+- The lens name in **bold**. (Lenses have no public URL \u2014 do not fabricate a link.)
+
+**Column 2 \u2014 Description**
+- \`description\` verbatim, clipped to \u2264 18 words.
+- When null/empty: render \`\u2014\`.
+
+**After a \`switched: true\` response**, open with a single confirmation line
+ABOVE the table: \`Now showing **<name>**.\` For \`status: "not_found"\`, lead with
+the \`message\` (the bad id) and render the list so the user can pick a real one.
+
+**Empty list** (\`lenses: []\`): render \`*You don't have any lenses yet.*\` \u2014 do not
+render an empty table.
+
+**Legend:** \u2B50 active lens.
+
+
+## NEXT STEPS \u2014 after \`leadbay_my_lenses\`
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick the 2\u20133 rows that fit what the user is likely to want next. When the user
+named no target but wants to switch, offer the lenses themselves as the
+quick-select options (each option = a lens name \u2192 \`leadbay_my_lenses(switchToLensId=<id>)\`).
+
+| Observation                          | Suggest                                  | Calls                                                |
+|--------------------------------------|------------------------------------------|------------------------------------------------------|
+| User wants a different lens          | "Switch to <lens name>"                  | \`leadbay_my_lenses(switchToLensId=<id>)\`             |
+| User wants to rename / describe a lens| "Rename or describe <lens>"             | \`leadbay_my_lenses(editLensId=<id>, newName?=<X>, newDescription?=<Y>)\` |
+| User wants to delete a lens          | "Delete <lens>"                          | \`leadbay_my_lenses(deleteLensId=<id>)\` \u2192 confirm \u2192 \`confirm=true\` |
+| \`delete_preview\` (not yet deleted)   | "Yes, delete it"                         | \`leadbay_my_lenses(deleteLensId=<id>, confirm=true)\` |
+| User wants leads on the active lens  | "Pull today's leads"                     | \`leadbay_pull_leads()\`                               |
+| User wants to change the audience    | "Adjust this lens's audience"            | \`leadbay_adjust_audience(...)\`                       |
+| User wants more of the same          | "Get a bigger batch on this lens"        | \`leadbay_extend_lens(...)\`                           |
+
+If nothing fits, default to "pull today's leads on the active lens" \u2014 never
+invent a tool that doesn't exist.
+`;
+var leadbay_new_lens = `## WHEN TO USE
+
+Trigger phrases: "create a lens", "create a new lens called <name>", "create a lens specialized in/into <X>", "make me a new audience for <X>", "set up a lens for <sector>", "new lens named <name>", "I want a lens just for <X>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "narrow the audience / add or remove a sector on an EXISTING lens" \u2192 \`leadbay_adjust_audience\`; "add <sector> to my <name> lens" \u2192 \`leadbay_adjust_audience\`; "focus on a qualitative trait beyond sector/size" \u2192 \`leadbay_refine_prompt\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`; "more leads on this lens" \u2192 \`leadbay_extend_lens\`.
+
+Prefer when: user wants a brand-new lens (create/make/set up, often 'specialized in <X>'). Editing an existing lens \u2192 leadbay_adjust_audience (use lensName). Qualitative refinement \u2192 refine_prompt (admin-only).
+
+Examples that SHOULD invoke this tool:
+- "Create a lens called Joinery for the fintech sector."
+- "Make me a new audience for healthcare companies, 30\u2013300 people."
+- "Set up a new lens named Nordics SaaS."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Add fintech to my Joinery lens."
+- "Show me my lenses."
+- "I want more leads on this lens."
+
+## RENDER (quick)
+
+On \`preview\` (default \u2014 NOTHING created yet): show the lens that WILL be
+created (name + resolved sectors/sizes as chips) and ASK the user to confirm
+via ask_user_input_v0 ("Create this lens?" / "Change something"). Only on
+"yes" re-call with confirm:true. On \`created\`: confirm "Created **<name>**."
+On \`ambiguous_sectors\`: surface the candidate sectors to pick from.
+
+---
+
+Create a brand-new lens (saved audience) and apply its sector/size criteria. Clones a base lens (the user's active/default lens unless \`base\` is given), names it, and applies the filter.
+
+**Confirm before creating \u2014 two-step by default.** A call WITHOUT \`confirm:true\` is a dry run: it resolves the sectors/sizes and returns \`status:"preview"\` with \`will_create\` (what it WOULD build) \u2014 **nothing is created**. Show that to the user, get an explicit yes (ask via \`ask_user_input_v0\`), then re-call the SAME args with \`confirm:true\` to actually create. Never pass \`confirm:true\` on the first call \u2014 the user must see the preview first. (Sector ambiguity is still surfaced in the preview step, so they pick before confirming.)
+
+**Sectors resolve first.** Free-text \`sectors\`/\`exclude_sectors\` are auto-resolved against the taxonomy. If any don't resolve, the tool returns \`status:"ambiguous_sectors"\` with the candidates and **does NOT create the lens** \u2014 so re-calling after picking the right sector won't leave orphan half-built lenses. To discover valid sector labels up front, use \`leadbay_list_sectors\`.
+
+**Does not switch the active lens.** The new lens is created but the user stays on their current one. Offer \`leadbay_my_lenses(switchToLensId=<new id>)\` as a next step if they want to start pulling from it.
+
+WHEN TO USE: when the user wants a NEW lens. Canonical phrasings: "create a lens called X", "make a new audience for Y", "set up a lens for <sector>".
+
+WHEN NOT TO USE: to EDIT an existing lens \u2014 use \`leadbay_adjust_audience\` (pass \`lensName\` to target one by name). Not for listing/switching (\`leadbay_my_lenses\`) or topping up (\`leadbay_extend_lens\`).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
+
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
+---
+
+## NEXT STEPS \u2014 after \`leadbay_new_lens\`
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick the rows that fit. On \`created\`, the switch + pull rows are the natural
+follow-ups. On \`ambiguous_sectors\`, the only move is to pick a sector and re-call.
+
+| Observation                       | Suggest                                  | Calls                                                  |
+|-----------------------------------|------------------------------------------|--------------------------------------------------------|
+| \`preview\` (not yet created)       | "Yes, create this lens"                  | \`leadbay_new_lens(...same args..., confirm=true)\`      |
+| \`preview\` (not yet created)       | "Change the sectors/size first"          | (re-ask the user, then \`leadbay_new_lens\` with new args) |
+| Lens created                      | "Switch to it and pull leads"            | \`leadbay_my_lenses(switchToLensId=<new id>)\` then \`leadbay_pull_leads()\` |
+| Lens created                      | "Refine the audience further"            | \`leadbay_adjust_audience(lensName=<new name>, ...)\`    |
+| Lens created                      | "Leave it; keep my current lens active"  | (no call)                                              |
+| \`ambiguous_sectors\`               | "Pick the right sector and create"       | \`leadbay_new_lens(name=..., sectors=[<chosen id>])\`    |
+
+If nothing fits, default to "switch to the new lens and pull leads" \u2014 never
+invent a tool that doesn't exist.
+`;
 var leadbay_open_billing_portal = `Generate a one-shot Stripe customer-portal URL. Wraps \`GET /1.5/stripe/portal\` \u2192 \`{url}\`. Returns a fresh Stripe-hosted URL the user can open to manage their existing Leadbay subscription: change plan tier, swap payment method, view invoices. The agent does NOT make subscription changes itself \u2014 it surfaces the URL and lets the user act.
 
 Sibling of \`leadbay_create_topup_link\`. Use cases differ:
@@ -8143,7 +8427,33 @@ WHEN TO USE: before leadbay_enrich_titles, to plan which titles to order.
 
 WHEN NOT TO USE: when you already know the exact titles you want to enrich.
 `;
-var leadbay_refine_prompt = `Refine the kind of leads Leadbay surfaces, beyond firmographics. Free-text instruction (e.g. "focus on hospitals running their own IT"). Sets the org's \`user_prompt\`; if the new prompt produces ambiguous criteria, Leadbay raises a clarification question, which this composite polls for and surfaces. Admin-only on the backend (will return 403 for non-admins).
+var leadbay_refine_prompt = `## WHEN TO USE
+
+Trigger phrases: "focus on companies that <qualitative trait>", "I prefer leads that <behavior/characteristic>", "prioritize companies running their own IT", "deprioritize companies that just raised".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "create a new lens / a lens specialized into <X>" \u2192 \`leadbay_new_lens\`; "add/remove <sector> to/from my <name> lens" \u2192 \`leadbay_adjust_audience\`; "narrow the audience to <sector> / <size>" \u2192 \`leadbay_adjust_audience\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`.
+
+Prefer when: ADMIN-ONLY. Qualitative refinement of the active lens that sector/size can't express. Creating/naming/listing/switching/sector-editing a lens routes elsewhere. Non-admin user \u2192 do NOT pick this.
+
+Examples that SHOULD invoke this tool:
+- "Focus on hospitals that run their own IT in-house."
+- "Prioritize companies that have recently expanded headcount."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a lens specialized in automobile."
+- "Add fintech to my Joinery lens."
+- "Show me my lenses."
+
+## RENDER (quick)
+
+On success: confirm the refinement applied to the active lens. If a
+clarification was raised, surface its question (route via ask_user_input_v0).
+
+---
+
+Refine the kind of leads Leadbay surfaces, beyond firmographics. Free-text instruction (e.g. "focus on hospitals running their own IT"). Sets the org's \`user_prompt\`; if the new prompt produces ambiguous criteria, Leadbay raises a clarification question, which this composite polls for and surfaces. Admin-only on the backend (will return 403 for non-admins).
 
 WHEN TO USE: when audience filters (leadbay_adjust_audience) aren't enough.
 
@@ -12118,7 +12428,7 @@ var createLens = {
   },
   execute: async (client, params) => {
     const lens = await client.request("POST", "/lenses", {
-      base: params.base,
+      base: String(params.base),
       name: params.name,
       description: params.description
     });
@@ -17373,6 +17683,8 @@ var bulkEnrichStatus = {
 
 // ../core/dist/composite/adjust-audience.js
 function tokens(s) {
+  if (!s)
+    return [];
   return s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
 }
 function bestMatches(text, taxonomy) {
@@ -17386,11 +17698,11 @@ function bestMatches(text, taxonomy) {
       if (have.has(t))
         overlap += 1;
     const score = overlap / Math.max(want.size, 1);
-    return { id: s.id, name: s.name, score };
+    return { id: s.id, name: s.name ?? "", score };
   }).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
   return ranked.slice(0, 5);
 }
-async function resolveSectors(client, texts) {
+async function resolveSectors(client, texts, ctx) {
   const looksLikeId2 = (s) => /^\d+$/.test(s);
   const direct = texts.filter(looksLikeId2);
   const free = texts.filter((s) => !looksLikeId2(s));
@@ -17399,6 +17711,10 @@ async function resolveSectors(client, texts) {
   const me = await client.resolveMe().catch(() => null);
   const lang = me?.language ?? "en";
   const taxonomy = await client.request("GET", `/sectors/all?lang=${encodeURIComponent(lang)}&includeInvisible=false`);
+  const nullNames = taxonomy.filter((s) => !s.name).length;
+  if (nullNames > 0) {
+    ctx?.logger?.warn?.(`adjust_audience: /sectors/all returned ${nullNames}/${taxonomy.length} sector(s) with a null/missing name`);
+  }
   const resolved = [...direct];
   const ambiguities = [];
   for (const text of free) {
@@ -17411,6 +17727,22 @@ async function resolveSectors(client, texts) {
   }
   return { resolved, ambiguities };
 }
+async function resolveLensByName(client, name) {
+  const lenses = await client.request("GET", "/lenses");
+  const all = lenses.map((l) => ({ id: l.id, name: l.name }));
+  const needle = name.trim().toLowerCase();
+  const exact = all.filter((l) => (l.name ?? "").trim().toLowerCase() === needle);
+  if (exact.length === 1)
+    return { ok: true, id: exact[0].id };
+  if (exact.length > 1)
+    return { ok: false, reason: "ambiguous", matches: exact };
+  const partial = all.filter((l) => (l.name ?? "").toLowerCase().includes(needle));
+  if (partial.length === 1)
+    return { ok: true, id: partial[0].id };
+  if (partial.length > 1)
+    return { ok: false, reason: "ambiguous", matches: partial };
+  return { ok: false, reason: "not_found", lenses: all };
+}
 function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
   const items = current?.lens_filter?.items ?? [];
   const item = items[0] ?? { criteria: [] };
@@ -17444,11 +17776,15 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
     }
   }
   if (sizes && sizes.length > 0) {
+    const normalizedSizes = sizes.map((s) => ({
+      min: s.min ?? 0,
+      max: s.max ?? 1e6
+    }));
     const idx = criteria.findIndex((c) => c.type === "size");
     if (idx >= 0) {
-      criteria[idx] = { type: "size", is_excluded: false, sizes };
+      criteria[idx] = { type: "size", is_excluded: false, sizes: normalizedSizes };
     } else {
-      criteria.push({ type: "size", is_excluded: false, sizes });
+      criteria.push({ type: "size", is_excluded: false, sizes: normalizedSizes });
     }
   }
   return {
@@ -17456,6 +17792,9 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
     locations: current.locations ?? { results: [], parents: [] }
   };
 }
+function filterWriteBody(filter) {
+  return { items: filter.lens_filter.items };
+}
 var adjustAudience = {
   name: "leadbay_adjust_audience",
   annotations: {
@@ -17497,6 +17836,10 @@ var adjustAudience = {
         description: "Company size buckets, e.g. [{min:30,max:300}]"
       },
       lensId: { type: "number", description: "Lens id (escape hatch)" },
+      lensName: {
+        type: "string",
+        description: "Target a lens BY NAME (e.g. 'Joinery') instead of the active one. Resolved against your lenses \u2014 edit-only, does NOT switch your active lens. Unknown/ambiguous names are surfaced to pick from. Takes effect only when lensId is not given."
+      },
       save_for_org: {
         type: "boolean",
         description: "Admin only \u2014 propagate the change to the org-level lens for everyone (default false: per-user draft)"
@@ -17510,21 +17853,35 @@ var adjustAudience = {
   },
   outputSchema: {
     type: "object",
-    description: "Two return shapes: 'ambiguous_sectors' when free-text sectors matched multiple candidates (agent re-calls with sector_ids), 'applied' on success.",
+    description: "Return shapes: 'applied' on success; 'ambiguous_sectors' when free-text sectors matched multiple candidates (re-call with sector_ids); 'lens_not_found' / 'ambiguous_lens' when a lensName didn't resolve to exactly one lens (re-call with lensId or an exact lensName).",
     properties: {
       status: {
         type: "string",
-        description: "'ambiguous_sectors' or 'applied'."
+        description: "'applied', 'ambiguous_sectors', 'lens_not_found', or 'ambiguous_lens'."
       },
       sector_ambiguities: {
         type: "array",
         description: "Per ambiguous text: {sector_text, matches:[{id, name, score}]}. Agent picks an id and re-calls.",
         items: { type: "object" }
       },
+      lenses: {
+        type: "array",
+        description: "On 'lens_not_found': the user's lenses [{id, name}] to pick from.",
+        items: { type: "object" }
+      },
+      matches: {
+        type: "array",
+        description: "On 'ambiguous_lens': the lenses [{id, name}] the name matched.",
+        items: { type: "object" }
+      },
+      lens_query: {
+        type: "string",
+        description: "On 'lens_not_found' / 'ambiguous_lens': the lensName the user asked for."
+      },
       message: { type: "string" },
       lens_used: {
         type: "object",
-        description: "Resolved lens metadata: {id, name, was_draft, was_new, save_for_org}."
+        description: "Resolved lens metadata: {id, name, was_draft, was_new, active_lens_changed, save_for_org}."
       },
       filter_applied: {
         type: "object",
@@ -17537,28 +17894,63 @@ var adjustAudience = {
   execute: async (client, params, ctx) => {
     const me = await client.resolveMe();
     const isAdmin = me.admin === true;
-    const startingLensId = params.lensId ?? me.last_requested_lens ?? await client.resolveDefaultLens();
+    let namedLensId;
+    if (params.lensId == null && params.lensName != null && params.lensName.trim() !== "") {
+      const res = await resolveLensByName(client, params.lensName);
+      if (!res.ok && res.reason === "not_found") {
+        return {
+          status: "lens_not_found",
+          lens_query: params.lensName,
+          lenses: res.lenses,
+          message: `No lens named "${params.lensName}". Pick one of the listed lenses (pass lensId or an exact lensName), or create it first.`
+        };
+      }
+      if (!res.ok && res.reason === "ambiguous") {
+        return {
+          status: "ambiguous_lens",
+          lens_query: params.lensName,
+          matches: res.matches,
+          message: `"${params.lensName}" matched multiple lenses. Re-call with the exact lensName or the lensId of the one you mean.`
+        };
+      }
+      if (res.ok)
+        namedLensId = res.id;
+    }
+    const startingLensId = params.lensId ?? namedLensId ?? me.last_requested_lens ?? await client.resolveDefaultLens();
+    const isNamedEdit = namedLensId != null && params.lensId == null;
     const includeTexts = [
       ...params.sectors ?? [],
       ...params.sector_ids ?? []
     ];
     const excludeTexts = params.exclude_sectors ?? [];
-    const includeRes = await resolveSectors(client, includeTexts);
-    const excludeRes = await resolveSectors(client, excludeTexts);
+    const includeRes = await resolveSectors(client, includeTexts, ctx);
+    const excludeRes = await resolveSectors(client, excludeTexts, ctx);
     const ambiguities = [
       ...includeRes.ambiguities,
       ...excludeRes.ambiguities
     ];
     if (ambiguities.length > 0) {
+      const noMatch = ambiguities.filter((a) => a.matches.length === 0);
+      const multi = ambiguities.filter((a) => a.matches.length > 0);
+      const parts = [];
+      if (noMatch.length > 0) {
+        const names = noMatch.map((a) => `"${a.sector_text}"`).join(", ");
+        parts.push(`Couldn't find a sector matching ${names}. Ask the user to rephrase or pick a known sector, then re-call with sector_ids=...`);
+      }
+      if (multi.length > 0) {
+        const names = multi.map((a) => `"${a.sector_text}"`).join(", ");
+        parts.push(`${names} matched multiple sectors. Pick from the matches and re-call with sector_ids=...`);
+      }
       return {
         status: "ambiguous_sectors",
         sector_ambiguities: ambiguities,
-        message: "One or more sector names matched multiple sectors. Pick from the matches and re-call with sector_ids=..."
+        message: parts.join(" ")
       };
     }
     const lens = await client.request("GET", `/lenses/${startingLensId}`);
     const currentFilter = await client.request("GET", `/lenses/${startingLensId}/filter`);
     const merged = mergeFilter(currentFilter, includeRes.resolved, excludeRes.resolved, params.sizes);
+    const mergedBody = filterWriteBody(merged);
     const isDefault = lens.is_default || lens.default;
     const isUserLevel = lens.user_id != null;
     const isOrgLevel = !isUserLevel && !isDefault;
@@ -17567,24 +17959,28 @@ var adjustAudience = {
     let wasNew = false;
     if (isDefault) {
       const name = params.newLensName ?? `Custom audience \u2014 ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
-      const newLens = await client.request("POST", "/lenses", {
-        base: startingLensId,
+      const newLens2 = await client.request("POST", "/lenses", {
+        base: String(startingLensId),
         name
       });
-      targetLensId = newLens.id;
+      targetLensId = newLens2.id;
       wasNew = true;
-      await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
-      await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+      await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
+      if (!isNamedEdit) {
+        await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+      }
     } else if (isUserLevel) {
       try {
-        await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, merged);
+        await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, mergedBody);
       } catch (err) {
         if (err?.code === "FORBIDDEN") {
           wasDraft = true;
           const draft = await client.request("POST", `/lenses/${startingLensId}/draft`);
           targetLensId = draft.id;
-          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
-          await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
+          if (!isNamedEdit) {
+            await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+          }
         } else {
           throw err;
         }
@@ -17596,7 +17992,7 @@ var adjustAudience = {
         const draft = await client.request("POST", `/lenses/${startingLensId}/draft`);
         targetLensId = draft.id;
         try {
-          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
+          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
         } catch (err) {
           ctx?.logger?.warn?.(`adjust_audience: filter on draft ${targetLensId} failed: ${err?.message}`);
           try {
@@ -17612,17 +18008,21 @@ var adjustAudience = {
           }
           throw err;
         }
-        await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+        if (!isNamedEdit) {
+          await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+        }
       } else {
         try {
-          await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, merged);
+          await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, mergedBody);
         } catch (err) {
           throw err;
         }
       }
     }
-    client.invalidateMe();
+    if (!isNamedEdit)
+      client.invalidateMe();
     client.invalidateDefaultLens();
+    const namedEditForkedMessage = isNamedEdit && (wasNew || wasDraft) ? ` Note: "${lens.name}" can't be edited in place, so the change was applied to a ${wasDraft ? "personal draft" : "new copy"} (id ${targetLensId}); your active lens is unchanged.` : "";
     return {
       status: "applied",
       lens_used: {
@@ -17630,10 +18030,11 @@ var adjustAudience = {
         name: lens.name,
         was_draft: wasDraft,
         was_new: wasNew,
+        active_lens_changed: !isNamedEdit && (wasNew || wasDraft),
         save_for_org: params.save_for_org === true && isAdmin && isOrgLevel
       },
       filter_applied: merged,
-      message: wasDraft ? "Applied to your personal draft of the org lens (your view only)." : wasNew ? `Created a new user-level lens "${lens.name}" with the filter (you can rename via leadbay_update_lens).` : "Applied directly to the lens.",
+      message: (wasDraft ? "Applied to your personal draft of the org lens (your view only)." : wasNew ? `Created a new user-level lens "${lens.name}" with the filter (you can rename via leadbay_update_lens).` : "Applied directly to the lens.") + namedEditForkedMessage,
       _meta: { region: client.region }
     };
   }
@@ -18005,6 +18406,384 @@ var extendLens = {
   }
 };
 
+// ../core/dist/composite/my-lenses.js
+var sid = (v) => v == null ? null : String(v);
+async function listWithActive(client) {
+  const lenses = await client.request("GET", "/lenses");
+  const me = await client.resolveMe().catch(() => null);
+  const activeFromMe = sid(me?.last_requested_lens);
+  const active_lens_id = activeFromMe ?? sid(lenses.find((l) => l.is_last_active)?.id) ?? null;
+  return {
+    active_lens_id,
+    lenses: lenses.map((l) => ({
+      id: sid(l.id),
+      name: l.name,
+      description: l.description ?? null,
+      is_active: sid(l.id) === active_lens_id,
+      is_default: l.is_default === true || l.default === true
+    }))
+  };
+}
+var myLenses = {
+  name: "leadbay_my_lenses",
+  annotations: {
+    title: "List, switch, edit, or delete your lenses",
+    // No args → pure read. The delete mode issues DELETE /lenses/:id (an
+    // irreversible side effect), so the tool is destructive — clients must
+    // treat it as approval-required, not auto-run. The delete path is itself
+    // confirm-gated (preview unless confirm:true). switch/edit are not
+    // idempotent across modes either, so don't claim idempotency.
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  description: leadbay_my_lenses,
+  inputSchema: {
+    type: "object",
+    properties: {
+      switchToLensId: {
+        type: ["string", "number"],
+        description: "When set, switch the active lens to this id (must be one of the user's lenses), then return the refreshed list."
+      },
+      editLensId: {
+        type: ["string", "number"],
+        description: "When set, edit this lens's metadata \u2014 provide newName and/or newDescription. Must be one of the user's lenses."
+      },
+      newName: {
+        type: "string",
+        description: "New lens name (used with editLensId)."
+      },
+      newDescription: {
+        type: "string",
+        description: "New lens description (used with editLensId). Pass an empty string to clear it."
+      },
+      deleteLensId: {
+        type: ["string", "number"],
+        description: "When set, delete this lens. DESTRUCTIVE \u2014 returns a delete_preview unless confirm:true. Cannot delete the default lens."
+      },
+      confirm: {
+        type: "boolean",
+        description: "Required (=true) to actually delete. Without it, deleteLensId returns a preview to confirm with the user first."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        description: "'listed', 'switched', 'already_active', 'edited', 'deleted', 'delete_preview' (confirm to proceed), 'cannot_delete_default', or 'not_found'."
+      },
+      switched: { type: "boolean", description: "True when this call changed the active lens." },
+      edited: { type: "boolean", description: "True when this call renamed/re-described a lens." },
+      deleted: { type: "boolean", description: "True when this call deleted a lens." },
+      will_delete: {
+        type: "object",
+        description: "On 'delete_preview': the lens that WILL be deleted {id, name}. Nothing removed yet."
+      },
+      active_lens_id: { type: ["string", "null"] },
+      lenses: {
+        type: "array",
+        description: "The user's lenses. Each: {id, name, description, is_active}.",
+        items: { type: "object" }
+      },
+      message: { type: "string" }
+    },
+    required: ["status", "lenses", "active_lens_id"]
+  },
+  execute: async (client, params) => {
+    if (params.deleteLensId != null) {
+      const targetId = sid(params.deleteLensId);
+      const before = await listWithActive(client);
+      const target = before.lenses.find((l) => l.id === targetId);
+      if (!target) {
+        return {
+          status: "not_found",
+          switched: false,
+          edited: false,
+          deleted: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `No lens with id ${targetId}. Pick one from the list.`
+        };
+      }
+      if (target.is_default) {
+        return {
+          status: "cannot_delete_default",
+          switched: false,
+          edited: false,
+          deleted: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `"${target.name}" is the default lens and can't be deleted.`
+        };
+      }
+      if (params.confirm !== true) {
+        return {
+          status: "delete_preview",
+          switched: false,
+          edited: false,
+          deleted: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          will_delete: { id: target.id, name: target.name },
+          message: `About to delete "${target.name}". This can't be undone. Confirm with the user, then re-call with confirm:true.`
+        };
+      }
+      await client.requestVoid("DELETE", `/lenses/${targetId}`);
+      client.invalidateMe();
+      client.invalidateDefaultLens();
+      const after = await listWithActive(client);
+      return {
+        status: "deleted",
+        switched: false,
+        edited: false,
+        deleted: true,
+        active_lens_id: after.active_lens_id,
+        lenses: after.lenses,
+        message: `Deleted "${target.name}".`
+      };
+    }
+    if (params.editLensId != null) {
+      const targetId = sid(params.editLensId);
+      const before = await listWithActive(client);
+      const target = before.lenses.find((l) => l.id === targetId);
+      if (!target) {
+        return {
+          status: "not_found",
+          switched: false,
+          edited: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `No lens with id ${targetId}. Pick one from the list.`
+        };
+      }
+      const body = {};
+      const newName = params.newName?.trim();
+      if (newName)
+        body.name = newName;
+      if (params.newDescription !== void 0)
+        body.description = params.newDescription;
+      if (Object.keys(body).length === 0) {
+        return {
+          status: "not_found",
+          switched: false,
+          edited: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `Nothing to change on "${target.name}" \u2014 provide newName and/or newDescription.`
+        };
+      }
+      await client.requestVoid("POST", `/lenses/${targetId}`, body);
+      client.invalidateDefaultLens();
+      const changed = [
+        body.name != null ? `renamed to "${body.name}"` : null,
+        body.description !== void 0 ? "description updated" : null
+      ].filter(Boolean).join(", ");
+      const after = await listWithActive(client);
+      return {
+        status: "edited",
+        switched: false,
+        edited: true,
+        active_lens_id: after.active_lens_id,
+        lenses: after.lenses,
+        message: `"${target.name}" \u2014 ${changed}.`
+      };
+    }
+    if (params.switchToLensId != null) {
+      const targetId = sid(params.switchToLensId);
+      const before = await listWithActive(client);
+      const target = before.lenses.find((l) => l.id === targetId);
+      if (!target) {
+        return {
+          status: "not_found",
+          switched: false,
+          edited: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `No lens with id ${targetId}. Pick an id from the list.`
+        };
+      }
+      if (target.is_active) {
+        return {
+          status: "already_active",
+          switched: false,
+          edited: false,
+          active_lens_id: before.active_lens_id,
+          lenses: before.lenses,
+          message: `"${target.name}" is already your active lens.`
+        };
+      }
+      await client.requestVoid("POST", `/lenses/${targetId}/update_last_requested`);
+      client.invalidateMe();
+      client.invalidateDefaultLens();
+      const after = await listWithActive(client);
+      return {
+        status: "switched",
+        switched: true,
+        edited: false,
+        active_lens_id: after.active_lens_id,
+        lenses: after.lenses,
+        message: `Now showing "${target.name}".`
+      };
+    }
+    const { lenses, active_lens_id } = await listWithActive(client);
+    return { status: "listed", switched: false, edited: false, active_lens_id, lenses };
+  }
+};
+
+// ../core/dist/composite/new-lens.js
+var EMPTY_FILTER = {
+  lens_filter: { items: [{ criteria: [] }] },
+  locations: { results: [], parents: [] }
+};
+var newLens = {
+  name: "leadbay_new_lens",
+  annotations: {
+    title: "Create a new named lens",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    // each call creates a distinct lens
+    openWorldHint: true
+  },
+  description: leadbay_new_lens,
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Display name for the new lens (required)." },
+      sectors: {
+        type: "array",
+        items: { type: "string" },
+        description: "Sectors to include \u2014 free text (auto-resolved) or ids."
+      },
+      exclude_sectors: {
+        type: "array",
+        items: { type: "string" },
+        description: "Sectors to exclude \u2014 free text or ids."
+      },
+      sizes: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { min: { type: "number" }, max: { type: "number" } }
+        },
+        description: "Company size buckets, e.g. [{min:30,max:300}]."
+      },
+      base: {
+        type: "number",
+        description: "Lens id to clone from. Defaults to the active/default lens."
+      },
+      description: { type: "string", description: "Optional lens description." },
+      confirm: {
+        type: "boolean",
+        description: "Safety gate. Defaults to false \u2192 the tool returns a PREVIEW and creates nothing. Show the preview to the user, get their explicit go-ahead, then re-call the SAME args with confirm:true to actually create the lens."
+      }
+    },
+    required: ["name"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    description: "'preview' (default, NOTHING created \u2014 confirm with the user then re-call with confirm:true); 'created' on success; 'ambiguous_sectors' when free-text sectors didn't resolve (re-call with sector ids \u2014 the lens was NOT created).",
+    properties: {
+      status: { type: "string", description: "'preview', 'created', 'ambiguous_sectors', or 'orphan_created' (filter write failed + cleanup failed)." },
+      will_create: {
+        type: "object",
+        description: "On 'preview': what WILL be created \u2014 {name, description, sectors, exclude_sectors, sizes}. Nothing has been written yet."
+      },
+      filter_preview: { type: "object", description: "On 'preview': the FilterPayload that would be applied." },
+      lens: {
+        type: "object",
+        description: "On 'created': the created lens {id, name}."
+      },
+      sector_ambiguities: {
+        type: "array",
+        description: "On 'ambiguous_sectors': per text {sector_text, matches:[{id,name,score}]}.",
+        items: { type: "object" }
+      },
+      filter_applied: { type: "object", description: "On 'created': the FilterPayload POSTed to the new lens." },
+      message: { type: "string" },
+      _meta: { type: "object" }
+    },
+    required: ["status"]
+  },
+  execute: async (client, params, ctx) => {
+    const includeRes = await resolveSectors(client, params.sectors ?? [], ctx);
+    const excludeRes = await resolveSectors(client, params.exclude_sectors ?? [], ctx);
+    const ambiguities = [...includeRes.ambiguities, ...excludeRes.ambiguities];
+    if (ambiguities.length > 0) {
+      const noMatch = ambiguities.filter((a) => a.matches.length === 0);
+      const multi = ambiguities.filter((a) => a.matches.length > 0);
+      const parts = [];
+      if (noMatch.length > 0) {
+        parts.push(`Couldn't find a sector matching ${noMatch.map((a) => `"${a.sector_text}"`).join(", ")}. Pick a known sector and re-call (lens not yet created).`);
+      }
+      if (multi.length > 0) {
+        parts.push(`${multi.map((a) => `"${a.sector_text}"`).join(", ")} matched multiple sectors. Pick from the matches and re-call with the sector id.`);
+      }
+      return {
+        status: "ambiguous_sectors",
+        sector_ambiguities: ambiguities,
+        message: parts.join(" ")
+      };
+    }
+    const merged = mergeFilter(EMPTY_FILTER, includeRes.resolved, excludeRes.resolved, params.sizes);
+    if (params.confirm !== true) {
+      return {
+        status: "preview",
+        will_create: {
+          name: params.name,
+          description: params.description ?? null,
+          sectors: includeRes.resolved,
+          exclude_sectors: excludeRes.resolved,
+          sizes: merged.lens_filter.items[0].criteria.find((c) => c.type === "size") ?? null
+        },
+        filter_preview: merged,
+        message: `About to create "${params.name}". Confirm with the user, then re-call with confirm:true.`,
+        _meta: { region: client.region }
+      };
+    }
+    const base = params.base ?? await client.resolveDefaultLens();
+    const created = await client.request("POST", "/lenses", {
+      base: String(base),
+      name: params.name,
+      description: params.description
+    });
+    const hasCriteria = merged.lens_filter.items[0].criteria.length > 0;
+    if (hasCriteria) {
+      try {
+        await client.requestVoid("POST", `/lenses/${created.id}/filter`, filterWriteBody(merged));
+      } catch (err) {
+        ctx?.logger?.warn?.(`new_lens: filter write on new lens ${created.id} failed: ${err?.message} \u2014 rolling back`);
+        try {
+          await client.requestVoid("DELETE", `/lenses/${created.id}`);
+        } catch {
+          client.invalidateDefaultLens();
+          return {
+            status: "orphan_created",
+            lens: { id: created.id, name: created.name },
+            message: `Created "${created.name}" but applying its filter failed, and cleanup also failed. The lens exists with no criteria \u2014 delete it via leadbay_my_lenses(deleteLensId:"${created.id}", confirm:true) or set its audience with leadbay_adjust_audience.`,
+            _meta: { region: client.region }
+          };
+        }
+        client.invalidateDefaultLens();
+        throw err;
+      }
+    }
+    client.invalidateDefaultLens();
+    return {
+      status: "created",
+      lens: { id: created.id, name: created.name },
+      filter_applied: merged,
+      message: `Created "${created.name}".`,
+      _meta: { region: client.region }
+    };
+  }
+};
+
 // ../core/dist/composite/answer-clarification.js
 var answerClarification = {
   name: "leadbay_answer_clarification",
@@ -18524,7 +19303,6 @@ var granularReadTools = [
   getQuota,
   getLensFilter,
   getLensScoring,
-  listSectors,
   listLocations,
   getUserPrompt,
   getClarification,
@@ -18595,6 +19373,11 @@ var compositeReadTools = [
   // it for discoverability; expose it always-on so agents can find custom fields
   // without needing LEADBAY_MCP_ADVANCED=1.
   listMappableFields,
+  // listSectors is granular-shaped but ALWAYS exposed: it's the sector taxonomy
+  // lookup the agent needs to STOP guessing sector names (and to feed
+  // leadbay_new_lens / leadbay_adjust_audience). Without it the agent can only
+  // probe sectors by trial-and-error or ask the user to read the web UI.
+  listSectors,
   // Billing / top-up tools — granular-shaped but ALWAYS exposed because
   // they're the canonical recovery path from a QUOTA_EXCEEDED wall. If
   // they were gated behind LEADBAY_MCP_ADVANCED=1 the agent would
@@ -18637,7 +19420,16 @@ var compositeWriteTools = [
   removeLeadsFromCampaign,
   // Lens extend — agent-driven on-demand fill (additive). Gated behind
   // LEADBAY_MCP_WRITE=1. Subject to per-org daily LENS_EXTRA_REFILL quota.
-  extendLens
+  extendLens,
+  // Lens list/switch — read-first (no args = pure list); a switchToLensId
+  // changes the active lens. In compositeWriteTools because the switch path
+  // mutates last_requested_lens, but it stays on the default surface
+  // (write is on by default since 0.3.0).
+  myLenses,
+  // Lens creation — make a brand-new named lens with sectors/sizes in one
+  // call. Default-surface so "create a lens called X for Y" works without
+  // the advanced gate.
+  newLens
 ];
 var compositeTools = [
   ...compositeReadTools,
@@ -19837,7 +20629,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.17.1" : "0.0.0-dev";
+var VERSION = true ? "0.17.3" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var sseSessions = /* @__PURE__ */ new Map();