@sodiumhq/mcp-pm 0.1.0-beta.4445 → 0.1.0-beta.4448

package/README.md

@@ -62,8 +62,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 - **`get_practice_dashboard`** — one-call "state of the practice right now": overdue/blocked/due-soon work, what clients are sitting on, unassigned steps, unbilled time, open proposal pipeline. *"Give me my morning briefing."*
 - **`get_practice_details`** — consolidated practice overview (counts, connections, settings)
 - **`whoami`** — show the authenticated user (name, email, code), tenant (name, code, status), and practice name. Useful for verifying which account is connected.
-- **`list_practices`** — list the practices you belong to, marking the active one. *"Which practices can I access?"*
-- **`set_active_practice`** — choose which practice to work in, or switch mid-session. *"Switch to Oceans."* Needed when you belong to more than one practice.
+- **`list_practices`** — list the practices you belong to. *"Which practices can I access?"* If you belong to more than one, tools take an optional `practice` code to say which one a request is about; with a single practice it is selected automatically.
 
 **Clients**
 - **`list_clients`** — list and filter clients by search, status, type, assignee, services, saved filters

package/dist/http.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-BRf2g74U.mjs";
+import { t as buildServer } from "./src-DEbTNFXg.mjs";
 import { createRequire } from "node:module";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { createServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
@@ -140,26 +140,6 @@ const WRITES_ENABLED = writesRaw === "true" || writesRaw === "1";
 const AUTH = loadAuthConfig();
 const OBO = AUTH ? loadOboConfig(AUTH.issuer) : null;
 const ENDPOINT_PATH = AUTH ? new URL(AUTH.resourceUrl).pathname : process.env.MCP_ENDPOINT_PATH ?? "/mcp";
-const sessions = /* @__PURE__ */ new Map();
-const SESSION_IDLE_MS = Number(process.env.MCP_SESSION_IDLE_MS ?? 30 * 6e4);
-const SWEEP_INTERVAL_MS = 6e4;
-function touch(sessionId) {
-	const session = sessions.get(sessionId);
-	if (session) session.lastActivity = Date.now();
-}
-async function sweepIdleSessions() {
-	const cutoff = Date.now() - SESSION_IDLE_MS;
-	for (const [sessionId, session] of sessions) {
-		if (session.lastActivity > cutoff) continue;
-		sessions.delete(sessionId);
-		console.error(`[sodium-pm-mcp-http] session ${sessionId} swept (idle)`);
-		try {
-			await session.transport.close();
-		} catch (error) {
-			console.error(`[sodium-pm-mcp-http] error closing swept session: ${String(error)}`);
-		}
-	}
-}
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
 async function readJsonBody(req) {
 	const chunks = [];
@@ -182,7 +162,7 @@ function sendJsonError(res, status, message) {
 		id: null
 	}));
 }
-async function createSession(req) {
+async function handleMcpPost(req, res, body) {
 	const authHeader = req.headers.authorization;
 	if (!authHeader?.startsWith("Bearer ")) throw new HttpError(401, "Authorization: Bearer <token> header is required.");
 	const bearerToken = authHeader.slice(7).trim();
@@ -195,6 +175,7 @@ async function createSession(req) {
 	}
 	const tenantHeader = req.headers["x-sodium-tenant"];
 	const tenant = (Array.isArray(tenantHeader) ? tenantHeader[0] : tenantHeader) ?? process.env.SODIUM_TENANT;
+	const isInit = isInitializeRequest(body);
 	const server = await buildServer({
 		context: {
 			bearerToken: apiToken,
@@ -203,26 +184,17 @@ async function createSession(req) {
 			writesEnabled: writesAllowed
 		},
 		serverName: "Sodium Practice Management",
-		serverVersion: VERSION
+		serverVersion: VERSION,
+		includeStartupContext: isInit
 	});
-	const transport = new StreamableHTTPServerTransport({
-		sessionIdGenerator: () => randomUUID(),
-		onsessioninitialized: (sessionId) => {
-			sessions.set(sessionId, {
-				transport,
-				lastActivity: Date.now()
-			});
-			console.error(`[sodium-pm-mcp-http] session ${sessionId} started (tenant: ${tenant}, live: ${sessions.size})`);
-		}
+	const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+	res.on("close", () => {
+		transport.close();
+		server.close();
 	});
-	transport.onclose = () => {
-		if (transport.sessionId) {
-			sessions.delete(transport.sessionId);
-			console.error(`[sodium-pm-mcp-http] session ${transport.sessionId} closed`);
-		}
-	};
+	if (isInit) console.error(`[sodium-pm-mcp-http] initialize (tenant: ${tenant || "per-call"}, writes: ${writesAllowed})`);
 	await server.connect(transport);
-	return transport;
+	await transport.handleRequest(req, res, body);
 }
 var HttpError = class extends Error {
 	constructor(status, message) {
@@ -235,8 +207,7 @@ async function handle(req, res) {
 	if (req.method === "GET" && url.pathname === "/health") {
 		res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({
 			status: "ok",
-			version: VERSION,
-			sessions: sessions.size
+			version: VERSION
 		}));
 		return;
 	}
@@ -248,25 +219,14 @@ async function handle(req, res) {
 		sendJsonError(res, 404, `Not found. MCP endpoint is ${ENDPOINT_PATH}.`);
 		return;
 	}
-	const sessionId = req.headers["mcp-session-id"];
-	const existing = typeof sessionId === "string" ? sessions.get(sessionId) : void 0;
-	if (existing && typeof sessionId === "string") {
-		touch(sessionId);
-		await existing.transport.handleRequest(req, res);
-		return;
-	}
 	if (req.method !== "POST") {
-		sendJsonError(res, 400, "No valid MCP session. Send an initialize request first.");
+		res.setHeader("Allow", "POST");
+		sendJsonError(res, 405, "Stateless MCP endpoint. Send requests as POST.");
 		return;
 	}
-	const body = await readJsonBody(req);
-	if (!isInitializeRequest(body)) {
-		sendJsonError(res, 400, "No valid MCP session. Send an initialize request first.");
-		return;
-	}
-	await (await createSession(req)).handleRequest(req, res, body);
+	await handleMcpPost(req, res, await readJsonBody(req));
 }
-const httpServer = createServer((req, res) => {
+createServer((req, res) => {
 	handle(req, res).catch((error) => {
 		const message = error instanceof Error ? error.message : String(error);
 		console.error(`[sodium-pm-mcp-http] ${req.method} ${req.url} failed: ${message}`);
@@ -280,11 +240,7 @@ const httpServer = createServer((req, res) => {
 		if (AUTH && error instanceof HttpError && error.status === 401) res.setHeader("WWW-Authenticate", buildChallenge(AUTH));
 		sendJsonError(res, error instanceof HttpError ? error.status : 500, message);
 	});
-});
-setInterval(() => {
-	sweepIdleSessions();
-}, SWEEP_INTERVAL_MS).unref();
-httpServer.listen(PORT, HOST, () => {
+}).listen(PORT, HOST, () => {
 	console.error(`[sodium-pm-mcp-http] v${VERSION} listening on http://${HOST}:${PORT}${ENDPOINT_PATH} (api: ${BASE_URL}, writes: ${WRITES_ENABLED ? "enabled" : "disabled"})`);
 });
 //#endregion

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as buildServer } from "./src-BRf2g74U.mjs";
+import { t as buildServer } from "./src-DEbTNFXg.mjs";
 import { createRequire } from "node:module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { parseArgs } from "node:util";

package/dist/{src-BRf2g74U.mjs → src-DEbTNFXg.mjs}

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 //#region ../mcp-core/src/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
 Object.entries({
@@ -2233,7 +2233,7 @@ var SodiumApiClient = class {
 		}));
 	}
 	get tenant() {
-		if (!this.activeTenant) throw new Error("No practice selected. Call set_active_practice with a code from list_practices first.");
+		if (!this.activeTenant) throw new Error("No practice specified. Pass a practice code from list_practices in the tool's 'practice' argument.");
 		return this.activeTenant;
 	}
 	hasActiveTenant() {
@@ -3576,13 +3576,13 @@ async function buildInstructions(api, writesEnabled, selection) {
 	if (tenant.status === "fulfilled") lines.push(`Tenant: ${tenant.value.name} (${tenant.value.code})`);
 	if (practice.status === "fulfilled") lines.push(`Practice: ${practice.value.name}`);
 	if (selection.kind === "choice") {
-		lines.push("", "PRACTICE SELECTION REQUIRED — this user belongs to more than one practice and none is active yet.", "Before using any client/task/other data tool, ask the user which practice to work in and call set_active_practice with its code.");
+		lines.push("", "PRACTICE SELECTION — this user belongs to more than one practice.", "Data tools take an optional 'practice' argument (a practice code). Ask the user which practice to work in, then pass its code on EVERY tool call for the rest of the conversation. Calls without it are refused with a reminder.");
 		if (selection.practices.length > 0) {
 			lines.push("Practices available:");
 			for (const p of selection.practices) lines.push(`- ${p.name} (${p.code})`);
 		} else lines.push("Call list_practices to see the available practices.");
 	} else if (selection.kind === "none") lines.push("", "This user does not belong to any usable practice. Tell them their Sodium account has no active practice and there is nothing to show.");
-	else if (selection.kind === "auto") lines.push("", `Working in ${selection.practice.name} (${selection.practice.code}) — the only practice this user belongs to. Call set_active_practice only if they ask to switch.`);
+	else if (selection.kind === "auto") lines.push("", `Working in ${selection.practice.name} (${selection.practice.code}) — the only practice this user belongs to. It is selected automatically; no 'practice' argument is needed.`);
 	lines.push("", writesEnabled ? "Write mode: ENABLED. Create/update tools are available; destructive and bulk operations are not." : "Write mode: DISABLED. Read-only — tell the user to relaunch with --enable-writes if they want changes made.");
 	if (team.status === "fulfilled") {
 		const members = team.value.data ?? [];
@@ -3629,12 +3629,34 @@ async function resolveTenant(api) {
 		practices: usable
 	};
 }
+async function resolveTenantForCall(api, practice) {
+	const explicit = practice?.trim();
+	if (explicit) {
+		api.setActiveTenant(explicit);
+		return { ok: true };
+	}
+	if (api.hasActiveTenant()) return { ok: true };
+	const selection = await resolveTenant(api);
+	if (selection.kind === "auto" || selection.kind === "explicit") return { ok: true };
+	if (selection.kind === "none") return {
+		ok: false,
+		message: "This user does not belong to any usable practice, so there is no practice data to work with."
+	};
+	if (selection.practices.length === 0) return {
+		ok: false,
+		message: "Could not determine which practice to work in. Call list_practices, ask the user to choose, then retry with the chosen code in the 'practice' argument."
+	};
+	return {
+		ok: false,
+		message: `This user belongs to more than one practice: ${selection.practices.map((p) => `${p.name} (${p.code})`).join(", ")}. Ask which practice to work in, then retry with the chosen code in the 'practice' argument.`
+	};
+}
 //#endregion
 //#region ../mcp-core/src/tools/list-practices.ts
 async function handleListPractices(api) {
 	try {
 		const memberships = await api.listTenants();
-		const active = api.getActiveTenant();
+		const pinned = api.getActiveTenant();
 		if (memberships.length === 0) return { content: [{
 			type: "text",
 			text: "You do not belong to any practices."
@@ -3642,10 +3664,10 @@ async function handleListPractices(api) {
 		return { content: [{
 			type: "text",
 			text: `Practices you belong to:\n${memberships.map((t) => {
-				const flags = [t.code === active ? "ACTIVE" : null, isUsablePractice(t) ? null : "unavailable"].filter(Boolean);
+				const flags = [t.code === pinned ? "default" : null, isUsablePractice(t) ? null : "unavailable"].filter(Boolean);
 				const suffix = flags.length > 0 ? ` — ${flags.join(", ")}` : "";
 				return `- ${t.name} (${t.code})${suffix}`;
-			}).join("\n")}\n\nUse set_active_practice with a code to switch.`
+			}).join("\n")}\n\nPass a code in the 'practice' argument of other tools to work in that practice.`
 		}] };
 	} catch (error) {
 		return {
@@ -3658,45 +3680,6 @@ async function handleListPractices(api) {
 	}
 }
 //#endregion
-//#region ../mcp-core/src/tools/set-active-practice.ts
-const SetActivePracticeInputSchema = { code: z.string().describe("The practice code to work in, from list_practices (e.g. 'oceans').") };
-async function handleSetActivePractice(api, args) {
-	try {
-		const memberships = await api.listTenants();
-		const match = memberships.find((t) => t.code === args.code);
-		if (!match) {
-			const known = memberships.map((t) => t.code).join(", ") || "(none)";
-			return {
-				content: [{
-					type: "text",
-					text: `'${args.code}' is not a practice you belong to. Your practices: ${known}.`
-				}],
-				isError: true
-			};
-		}
-		if (!isUsablePractice(match)) return {
-			content: [{
-				type: "text",
-				text: `'${match.name}' (${match.code}) is not currently available and cannot be selected.`
-			}],
-			isError: true
-		};
-		api.setActiveTenant(match.code);
-		return { content: [{
-			type: "text",
-			text: `Now working in ${match.name} (${match.code}).`
-		}] };
-	} catch (error) {
-		return {
-			content: [{
-				type: "text",
-				text: `Could not switch practice: ${error instanceof Error ? error.message : String(error)}`
-			}],
-			isError: true
-		};
-	}
-}
-//#endregion
 //#region ../mcp-core/src/tools/get-practice-details.ts
 function format$4(tenant, practice) {
 	const lines = [];
@@ -8759,14 +8742,39 @@ async function handleCreateSavedTaskFilter(api, args) {
 }
 //#endregion
 //#region ../mcp-core/src/server.ts
-function registerWriteTool(server, ctx, name, config, cb) {
+const practiceField = z.string().optional().describe("Practice code to run this call against, from list_practices. Needed only when the user belongs to more than one practice; omit when they have exactly one — it is selected automatically.");
+function registerTenantTool(server, api, name, config, cb) {
+	const inputSchema = {
+		...config.inputSchema ?? {},
+		practice: practiceField
+	};
+	server.registerTool(name, {
+		...config,
+		inputSchema
+	}, async (args, extra) => {
+		const { practice, ...rest } = args;
+		const resolution = await resolveTenantForCall(api, typeof practice === "string" ? practice : void 0);
+		if (!resolution.ok) return {
+			content: [{
+				type: "text",
+				text: resolution.message
+			}],
+			isError: true
+		};
+		return cb(rest, extra);
+	});
+}
+function registerWriteTool(server, api, ctx, name, config, cb) {
 	if (!ctx.writesEnabled) return;
-	server.registerTool(name, config, cb);
+	registerTenantTool(server, api, name, config, cb);
 }
 async function buildServer(config) {
 	const api = new SodiumApiClient(config.context, { serverVersion: config.serverVersion });
-	const selection = api.hasActiveTenant() ? { kind: "explicit" } : await resolveTenant(api);
-	const instructions = await buildInstructions(api, config.context.writesEnabled, selection);
+	let instructions;
+	if (config.includeStartupContext !== false) {
+		const selection = api.hasActiveTenant() ? { kind: "explicit" } : await resolveTenant(api);
+		instructions = await buildInstructions(api, config.context.writesEnabled, selection);
+	}
 	const server = new McpServer({
 		name: config.serverName,
 		version: config.serverVersion,
@@ -8790,7 +8798,7 @@ async function buildServer(config) {
 			version: info.version
 		});
 	};
-	server.registerTool("get_practice_details", {
+	registerTenantTool(server, api, "get_practice_details", {
 		title: "Get practice details",
 		description: "Get a consolidated overview of the practice including name, contact details, client/service/user counts, connections, and settings. Use this when the user asks about their practice, tenant, or wants a summary of their account.",
 		inputSchema: {},
@@ -8802,17 +8810,20 @@ async function buildServer(config) {
 	}, () => handleGetPracticeDetails(api));
 	server.registerTool("whoami", {
 		title: "Show current user and tenant info",
-		description: "Returns the identity of the authenticated API key user (name, email, code), the tenant they belong to (name, code, status, package), and the practice name. Use this when the user asks 'who am I?', 'which tenant am I connected to?', 'what account is this?', or when debugging authentication/permission issues.",
-		inputSchema: {},
+		description: "Returns the identity of the authenticated user (name, email, code), the tenant/practice the call runs against (name, code, status), and the practice name. Use this when the user asks 'who am I?', 'which tenant am I connected to?', 'what account is this?', or when debugging authentication/permission issues. The optional 'practice' argument picks the practice section shown; without it the user's lone practice is used, and the identity section still answers when no practice can be resolved.",
+		inputSchema: { practice: practiceField },
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: true,
 			openWorldHint: true
 		}
-	}, () => handleWhoami(api));
+	}, async (args) => {
+		await resolveTenantForCall(api, args.practice);
+		return handleWhoami(api);
+	});
 	server.registerTool("list_practices", {
 		title: "List the practices you can work in",
-		description: "List the practices (tenants) the signed-in user belongs to, marking which one is currently active. Use this when the user belongs to more than one practice and you need to confirm which to work in, when the user asks 'which practices can I access?', or before set_active_practice. Practices flagged 'unavailable' cannot be selected.",
+		description: "List the practices (tenants) the signed-in user belongs to. Use this when the user belongs to more than one practice and you need the codes to pass in other tools' 'practice' argument, or when the user asks 'which practices can I access?'. Practices flagged 'unavailable' cannot be worked in.",
 		inputSchema: {},
 		annotations: {
 			readOnlyHint: true,
@@ -8820,18 +8831,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, () => handleListPractices(api));
-	server.registerTool("set_active_practice", {
-		title: "Choose which practice to work in",
-		description: "Set the practice all subsequent tools operate on for this session. Required before other tools can run if the user belongs to more than one practice and none is active yet. Also use it to switch practice mid-session ('switch to Oceans', 'now look at Greggs'). Pass a practice code from list_practices. Only practices the user belongs to and that are currently available can be selected.",
-		inputSchema: SetActivePracticeInputSchema,
-		annotations: {
-			readOnlyHint: false,
-			destructiveHint: false,
-			idempotentHint: true,
-			openWorldHint: true
-		}
-	}, (args) => handleSetActivePractice(api, args));
-	server.registerTool("list_clients", {
+	registerTenantTool(server, api, "list_clients", {
 		title: "List / search / filter clients",
 		description: "List clients with any combination of: search (code/name/internal reference, 3+ chars), status (Active/Inactive/Prospect/LostProspect), type (PrivateLimitedCompany/PublicLimitedCompany/LimitedLiabilityPartnership/Partnership/Individual/Trust/Charity/SoleTrader), manager/partner/associate user codes, service codes, a saved filter code, sort, and pagination. Use search for 'find ACME'-style queries. Use type for 'list limited companies' (pass PrivateLimitedCompany + PublicLimitedCompany). Use status: ['Active'] to exclude prospects/inactive. Returns up to 50 clients per page — paginate via offset for more. For 'how many X?' questions, pass limit=0 to get just the total count without fetching any client data. Follow up with get_client_summary for full detail on a specific client.",
 		inputSchema: ListClientsInputSchema,
@@ -8841,7 +8841,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListClients(api, args));
-	server.registerTool("get_client_summary", {
+	registerTenantTool(server, api, "get_client_summary", {
 		title: "Get a full summary of one client",
 		description: "Get a consolidated overview of a single client by code: identity (name, status, type, assignments), business details (company number, incorporation date, trading name, registered address, VAT status, UTR, PAYE ref), custom fields (all user-defined fields with current values, data types, and field codes — use these codes with update_client_custom_fields), key statutory dates (year-end, accounts due, VAT return due, confirmation statement due, etc. — upcoming first, then past), all contacts, active services with pricing, overdue task count + top 5, and tasks due in the next 7 days. Use this AFTER list_clients identifies the client of interest, or when the user references a specific client by code. Also answers 'when is ACME's year-end?' / 'is ACME VAT registered?' / 'what are ACME's custom fields?' in a single call. Tolerates partial failures — if one section can't be loaded, the rest is still returned with a note about what's missing.",
 		inputSchema: GetClientSummaryInputSchema,
@@ -8851,7 +8851,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetClientSummary(api, args));
-	server.registerTool("get_custom_field_details", {
+	registerTenantTool(server, api, "get_custom_field_details", {
 		title: "Get full details of a custom field definition",
 		description: "Get the full definition of a single custom field by code, including allowed options for Select and MultiSelect fields. The list endpoint and get_client_summary show field codes, labels, and data types but omit the allowed options — use this tool when you need to know the valid values before setting a Select or MultiSelect field via update_client_custom_fields. Also shows applicable client types and archived status.",
 		inputSchema: GetCustomFieldDetailsInputSchema,
@@ -8861,7 +8861,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetCustomFieldDetails(api, args));
-	server.registerTool("list_client_notes", {
+	registerTenantTool(server, api, "list_client_notes", {
 		title: "List / search notes on a client",
 		description: "List notes attached to a client, with optional search and author filter. Answers 'show me the notes on ACME', 'what has Jane noted about this client?', 'search notes for VAT'. Notes are returned newest first by default. Each note shows its code, date, author, pinned status, and text (truncated to 200 chars).",
 		inputSchema: ListClientNotesInputSchema,
@@ -8871,7 +8871,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListClientNotes(api, args));
-	server.registerTool("list_tasks", {
+	registerTenantTool(server, api, "list_tasks", {
 		title: "List / filter tasks across the practice",
 		description: "List tasks with any combination of filters: assigned user(s), client(s), status, overdue flag, preset date range (Today / ThisWeek / Next7Days / CustomDateRange etc), category, team, recurring task template, saved filter, include-projected, include-workflow-steps (Agenda Mode), sort, and pagination. Use for: 'my tasks' (pass current user's code from startup context), 'Jane's overdue tasks' (user + isOverdue), 'tasks for ACME due this week' (client + dateRange=Next7Days + dateBasis=DueDate), 'what is the team working on this month' (dateRange=ThisMonth, no user filter). Returns up to 50 tasks per page. IMPORTANT constraints to avoid API errors and keep queries efficient: (1) Querying NotStarted tasks requires one of — a dateRange, isOverdue=true, or restricting status to non-NotStarted values. (2) Prefer the narrowest date range that answers the question — broad ranges (quarterly/yearly) are expensive; prefer Today / ThisWeek / Next7Days / ThisMonth over larger windows unless explicitly asked. (3) For 'oldest incomplete tasks' prefer status=['InProgress','Blocked'] with sortBy=StartDate (no date range needed), or add isOverdue=true if 'oldest overdue' is meant. (4) For 'how many X?' questions, pass limit=0 to get just the total count without fetching any task data — much cheaper than fetching a full page and counting.",
 		inputSchema: ListTasksInputSchema,
@@ -8881,7 +8881,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListTasks(api, args));
-	server.registerTool("get_task_context", {
+	registerTenantTool(server, api, "get_task_context", {
 		title: "Get full context for a single task",
 		description: "Get a consolidated view of one task by code: identity (name, code, status, overdue flag, start/due/statutory dates, time estimate, assignee), description, task-level checklist, workflow progress (groups and steps with status, assignee, and completion info — only if the task has a workflow attached), notes (pinned first, then newest first), and the parent client. Use this AFTER list_tasks identifies a task of interest, or when the user references a specific task by code. Tolerates partial failures — if notes or workflow steps can't be loaded, the task details are still returned with a note about what's missing. Only fails outright if the task itself can't be fetched (e.g. unknown code).",
 		inputSchema: GetTaskContextInputSchema,
@@ -8891,7 +8891,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetTaskContext(api, args));
-	server.registerTool("list_proposals", {
+	registerTenantTool(server, api, "list_proposals", {
 		title: "List / filter proposals",
 		description: "List proposals (pre-acceptance engagement documents) with filters: status (Unsent/Sent/Viewed/Accepted/Rejected), search (engagement code / client name / client code, 3+ chars), preset date range, sort, pagination. Use for 'proposals awaiting acceptance' (status=Sent, or run twice for Sent + Viewed), 'proposals sent to ACME' (search), 'proposals sent this month' (dateRange=ThisMonth). Returns the same underlying data as list_engagement_letters — both aliases back the same Engagement entity; the status filter is what distinguishes a proposal (Unsent/Sent/Viewed/Rejected) from a signed letter of engagement (Accepted). For 'how many X?' questions, pass limit=0 for count-only. Follow up with get_proposal_summary for full detail on one engagement.",
 		inputSchema: ListEngagementsInputSchema,
@@ -8901,7 +8901,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListEngagements(api, args));
-	server.registerTool("list_engagement_letters", {
+	registerTenantTool(server, api, "list_engagement_letters", {
 		title: "List / filter letters of engagement",
 		description: "List letters of engagement (signed/accepted or in-flight engagement documents) with filters: status (Unsent/Sent/Viewed/Accepted/Rejected), search (engagement code / client name / client code, 3+ chars), preset date range, sort, pagination. Use for 'live letters of engagement' or 'signed engagements' (status=Accepted), 'letter of engagement for ACME' (search), 'engagements signed this quarter' (status=Accepted + dateRange=ThisQuarter). Returns the same underlying data as list_proposals — both aliases back the same Engagement entity; the status filter narrows the pipeline stage. For 'how many X?' questions, pass limit=0 for count-only. Follow up with get_engagement_letter_summary for full detail on one engagement.",
 		inputSchema: ListEngagementsInputSchema,
@@ -8911,7 +8911,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListEngagements(api, args));
-	server.registerTool("get_proposal_summary", {
+	registerTenantTool(server, api, "get_proposal_summary", {
 		title: "Get full detail of one proposal",
 		description: "Get a consolidated view of a single proposal by engagement code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off / total), the proposed services with pricing, acceptance record (if accepted), PDF availability (proposal + letter of engagement), email history, and the acceptance link. REQUIRES a concrete engagement code as input — do NOT call this tool unless you already have the code. If the user describes an engagement by attribute — e.g. 'the unsent proposal', 'the proposal for ACME', 'our most recent proposal', 'the rejected one' — you MUST call list_proposals FIRST with the matching filters to look up the code, then call this tool with that code. Returns identical data to get_engagement_letter_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history may be missing with a note); only fails hard if the engagement itself can't be fetched.",
 		inputSchema: GetEngagementSummaryInputSchema,
@@ -8921,7 +8921,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetEngagementSummary(api, args));
-	server.registerTool("get_engagement_letter_summary", {
+	registerTenantTool(server, api, "get_engagement_letter_summary", {
 		title: "Get full detail of one letter of engagement",
 		description: "Get a consolidated view of a single letter of engagement by code: identity (code, status, type, date), client, recipient, value breakdown (annual / quarterly / monthly / one-off / total), services included with pricing, acceptance record (accepted date, whether accepted via portal or recorded manually), PDF availability (proposal + letter of engagement), email history, and the acceptance link. REQUIRES a concrete engagement code as input — do NOT call this tool unless you already have the code. If the user describes the engagement by attribute — e.g. 'ACME's letter of engagement', 'the most recent signed engagement', 'the live engagement for Smith & Co' — you MUST call list_engagement_letters FIRST with the matching filters to look up the code, then call this tool with that code. Returns identical data to get_proposal_summary — both aliases back the same Engagement entity. Tolerates partial failures (email history may be missing with a note); only fails hard if the engagement itself can't be fetched.",
 		inputSchema: GetEngagementSummaryInputSchema,
@@ -8931,7 +8931,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetEngagementSummary(api, args));
-	server.registerTool("list_services", {
+	registerTenantTool(server, api, "list_services", {
 		title: "List / search / filter the practice's service catalogue",
 		description: "List the practice's configured billable services with any combination of: search (3+ chars over code and name), category (Tax / Payroll / CoreAccounting / CompanySecretarial / Advisory / SoftwareAndTraining / Other — single value), clientType (PrivateLimitedCompany / PublicLimitedCompany / LimitedLiabilityPartnership / Partnership / Individual / Trust / Charity / SoleTrader — single value; matches services configured for that type plus services with no client-type restriction), isArchived (omit for all, false for active only, true for archive), sort (Name / Category / AccountingCode), and pagination. Use for: 'what services do we offer?' (no filter, isArchived=false), 'list our tax services' (category=Tax), 'what do we offer limited companies?' (clientType=PrivateLimitedCompany, isArchived=false), 'how many active services do we have?' (isArchived=false, limit=0 for count-only). Returns up to 50 per page. Follow up with get_service_details for one service's full configuration (client types, pricing options, clearance items, HMRC authorisations).",
 		inputSchema: ListServicesInputSchema,
@@ -8941,7 +8941,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListServices(api, args));
-	server.registerTool("get_service_details", {
+	registerTenantTool(server, api, "get_service_details", {
 		title: "Get a single service's full configuration",
 		description: "Get a consolidated view of one billable service by code: identity (name, code, category, status, VAT rate, accounting code, description, default manager, pricing mode), applicable client types (explicit list, or 'all client types' if unrestricted), HMRC agent authorisations, pricing options (one per billing frequency with base price + override counts), custom pricing tiers (only when pricingMode=CustomTiers), professional clearance request items, and pricing-factor presence (count + factor questions only — exact factor band values are intentionally not dumped; computed pricing per client lives in the proposal tools). Use this AFTER list_services identifies the service, or when the user references a specific service by code. Enables service-audit workflows like 'is Self Assessment correctly restricted to Individual clients?' and 'what clearance items do we request for new bookkeeping clients?'",
 		inputSchema: GetServiceDetailsInputSchema,
@@ -8951,7 +8951,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleGetServiceDetails(api, args));
-	server.registerTool("list_users", {
+	registerTenantTool(server, api, "list_users", {
 		title: "List / search / filter tenant users",
 		description: "Find tenant users by name, email, role, or status. Use this when the user mentioned in a request isn't present in the startup roster (large teams have more than the top 20 active members shown there), or when filtering is needed beyond name resolution. Typical queries: 'find Jane' (search), 'list all partners' (isPartner=true), 'who's been invited but not joined yet?' (status=Invited), 'how many active users do we have?' (status=Active, limit=0). For 'how many X?' questions, pass limit=0 to get just the total count without fetching any user data.",
 		inputSchema: ListUsersInputSchema,
@@ -8961,7 +8961,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListUsers(api, args));
-	server.registerTool("list_contacts", {
+	registerTenantTool(server, api, "list_contacts", {
 		title: "List / search contacts across the practice",
 		description: "Find contacts by free-text search (name, email, phone, code — minimum 3 characters) or filter to contacts linked to a specific client. Answers 'find John Smith', 'who are the contacts for ACME?', 'search for jane@example.com', 'how many contacts do we have?'. Supports pagination and sorting by Name, FirstName, LastName, or ClientCount.",
 		inputSchema: ListContactsInputSchema,
@@ -8971,7 +8971,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleListContacts(api, args));
-	server.registerTool("get_contact", {
+	registerTenantTool(server, api, "get_contact", {
 		title: "Get full details of a contact",
 		description: "Get all fields for a single contact by code: name, title, email, phone, mobile, address, date of birth, nationality, marital status, UTR, NI number, Companies House person code, deceased status, linked clients, and portal user. Use after list_contacts identifies the contact of interest, or when the user asks for details about a specific contact. Also useful before update_contact to see current values.",
 		inputSchema: GetContactInputSchema,
@@ -8986,49 +8986,49 @@ async function buildServer(config) {
 		idempotentHint: true,
 		openWorldHint: true
 	};
-	server.registerTool("get_service_delivery_report", {
+	registerTenantTool(server, api, "get_service_delivery_report", {
 		title: "Service delivery turnaround report",
 		description: "Are we delivering client services as quickly as we should? Cohort = tasks COMPLETED in the window. Summary KPIs (count, avg/median turnaround from planned start to completion, on-time %, statutory compliance %, currently-overdue snapshot) plus a breakdown grouped by Service (default), Client, AssignedUser, or Month. Answers 'how fast do we turn around VAT returns?', 'which clients' work runs late?', 'is our turnaround improving month on month?' (groupBy=Month over a long window). NOT the right tool for missed deadlines — a task still open past its deadline never completed, so it isn't in this cohort; use get_deadline_compliance_report for that. For per-step bottlenecks within one service, follow up with get_service_delivery_steps. Constraints: dateRange='CustomDateRange' requires both startDate and endDate; summary always covers the whole cohort even when breakdown rows are paged.",
 		inputSchema: GetServiceDeliveryReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetServiceDeliveryReport(api, args));
-	server.registerTool("get_service_delivery_steps", {
+	registerTenantTool(server, api, "get_service_delivery_steps", {
 		title: "Per-step bottlenecks for one service",
 		description: "Where does the time go inside one billable service's workflow? For tasks of the given service completed in the window: average elapsed days per workflow step (measured from the previous step's completion, so queue/idle time counts), skip counts, chase counts, and each step flagged client-wait (waiting on the client: document requests, approvals, confirmations, data forms) vs internal — splitting 'we were slow' from 'the client was slow'. Use AFTER get_service_delivery_report flags a slow service, or directly for 'why do accounts jobs take so long?'. Requires serviceCode (from list_services). Note: steps are compared by name across tasks, so a renamed workflow step appears as separate rows.",
 		inputSchema: GetServiceDeliveryStepsInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetServiceDeliverySteps(api, args));
-	server.registerTool("get_deadline_compliance_report", {
+	registerTenantTool(server, api, "get_deadline_compliance_report", {
 		title: "Deadline compliance report",
 		description: "Which deadlines did we miss, and which are we about to? Cohort = every non-Skipped task whose chosen deadline (internal due date by default, or statutory via deadlineType='StatutoryDueDate') FELL in the window, whatever the task's status — so misses that are still open count, unlike the completion-anchored service delivery report. Each deadline is exactly one of: met, completed late, missed & still open (the actionable ones), or not yet due (excluded from the compliance rate). Also returns a forward-looking now-snapshot of OPEN tasks bucketed by days remaining (overdue / 0-7 / 8-14 / 15-30 / 31+), which ignores the date window. Answers 'which statutory deadlines did we miss last quarter?' (deadlineType=StatutoryDueDate, dateRange=PreviousQuarter), 'what's at risk this week?' (read the upcoming buckets), 'who keeps missing deadlines?' (groupBy=AssignedUser). Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: GetDeadlineComplianceReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetDeadlineComplianceReport(api, args));
-	server.registerTool("get_client_responsiveness_report", {
+	registerTenantTool(server, api, "get_client_responsiveness_report", {
 		title: "Client responsiveness report",
 		description: "Is it us or the client? Response times and chase pressure over CLIENT-FACING workflow steps (document requests, document approvals, client confirmations, data forms) completed in the window: how long clients take to respond (step sent to step completed), how much chasing it takes, plus a now-snapshot of steps currently waiting on a client. Group by Client (default — 'which clients are slowest to respond?'), Service, or StepType ('do clients answer confirmations faster than document requests?'). Use when slow delivery might be the client's fault rather than the practice's. Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: GetClientResponsivenessReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetClientResponsivenessReport(api, args));
-	server.registerTool("get_team_workload_report", {
+	registerTenantTool(server, api, "get_team_workload_report", {
 		title: "Team workload and productivity report",
 		description: "Who's overloaded, and who completes what? Two-sided rows per person (or team via groupBy='Team'): the open-workload NOW-snapshot (open / overdue / blocked counts — not affected by the date window) alongside completion throughput over the window (completions, average turnaround, on-time rate; completions attribute to whoever completed the task, not the assignee). Includes an Unassigned bucket. Answers 'who has capacity?', 'how much is on Jane's plate vs what she's shipping?', 'is anyone drowning in overdue work?'. Rows are bounded by team size — never paged. Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: GetTeamWorkloadReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetTeamWorkloadReport(api, args));
-	server.registerTool("get_wip_ageing_report", {
+	registerTenantTool(server, api, "get_wip_ageing_report", {
 		title: "WIP / ageing report",
 		description: "What's sitting untouched? A pure NOW-snapshot (the only report with no date window) of open tasks whose planned start date has arrived — how many, how old (age = planned start to today), and where they're stuck. Group by AgeBucket (default: 0-7/8-14/15-30/31-60/61+ days), Status, Service, Client, AssignedUser, or CurrentStep (the workflow step each task is sitting at — best for 'where is work stuck?'). Answers 'what's been sitting untouched the longest?', 'how much WIP do we have?', 'what's blocked right now?'.",
 		inputSchema: GetWipAgeingReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetWipAgeingReport(api, args));
-	server.registerTool("get_workflow_step_analysis", {
+	registerTenantTool(server, api, "get_workflow_step_analysis", {
 		title: "Workflow step analysis report",
 		description: "For ONE workflow template, where does the time go across its runs? Cohort = tasks spawned from the workflow and completed in the window. Per-step duration distributions in workflow order — median/avg/p90/best/worst elapsed days (best and worst carry their task codes so outliers are one call away), active time (the step's own start-to-complete, vs elapsed which includes queueing), skip and chase counts, client-wait vs internal classification — plus summary totals. Requires workflowCode. Differs from get_service_delivery_steps by anchoring on the workflow template (homogeneous runs, richer distributions) rather than a billable service. Treat distributions over fewer than ~5 occurrences as noise (the response flags this). For the slowest individual runs, follow up with list_workflow_occurrences. Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: GetWorkflowStepAnalysisInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetWorkflowStepAnalysis(api, args));
-	server.registerTool("list_workflow_occurrences", {
+	registerTenantTool(server, api, "list_workflow_occurrences", {
 		title: "List a workflow's completed runs, slowest first",
 		description: "One row per completed run (task) of a workflow template in the window, SLOWEST FIRST: task, client, completion date, total elapsed days, and the client-wait vs internal split. The drill-down companion to get_workflow_step_analysis — use for 'show me the ten slowest VAT-return runs this quarter' or to find the outlier tasks dragging the averages. Requires workflowCode. Paged (default 10 per page). Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: ListWorkflowOccurrencesInputSchema,
@@ -9049,217 +9049,217 @@ async function buildServer(config) {
 		idempotentHint: true,
 		openWorldHint: true
 	};
-	server.registerTool("list_workflows", {
+	registerTenantTool(server, api, "list_workflows", {
 		title: "List / search workflow templates",
 		description: "List the practice's workflow templates with search, sort (Name / GroupCount / StepCount / UpdatedDate), and pagination. Each row shows the code, group/step counts, and whether a client is required. This is THE way to resolve a workflow name ('our VAT workflow') to the workflowCode required by get_workflow_step_analysis, list_workflow_occurrences, and list_recurring_tasks' workflow filter. Also answers 'what workflows do we have?' and (limit=0) 'how many?'. Follow up with get_workflow for one template's full step structure.",
 		inputSchema: ListWorkflowsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListWorkflows(api, args));
-	server.registerTool("get_workflow", {
+	registerTenantTool(server, api, "get_workflow", {
 		title: "Get one workflow template's full structure",
 		description: "Get a single workflow template by code: the ordered groups and steps with step types (email, document request, approval, client confirmation, data form, etc.), assignment rules, auto-execute flags, dependencies, time estimates, and conditions. Answers 'what are the steps in our VAT return workflow?' and 'which steps in this workflow wait on the client?'. REQUIRES a concrete workflow code — call list_workflows first if the user named the workflow instead. For how the workflow performs in practice (durations, bottlenecks), use get_workflow_step_analysis.",
 		inputSchema: GetWorkflowInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetWorkflow(api, args));
-	server.registerTool("list_teams", {
+	registerTenantTool(server, api, "list_teams", {
 		title: "List teams and their members",
 		description: "List the practice's teams with their member rosters (name + code per member). Use to resolve a team name ('the payroll team') to the team code accepted by list_tasks' team filter, create_task/update_task's assignedTeamCode, and the report tools' team cohorts — and to answer 'what teams do we have?' / 'who's in the tax team?'. Note the members list also gives you user codes, so this doubles as a name→code lookup for people organised by team.",
 		inputSchema: ListTeamsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListTeams(api, args));
-	server.registerTool("list_task_categories", {
+	registerTenantTool(server, api, "list_task_categories", {
 		title: "List task categories",
 		description: "List the practice's task categories (code + name, in the practice's own sort order). Use to resolve a category name ('compliance work') to the categoryCode accepted by list_tasks, list_recurring_tasks, list_document_requests, list_data_form_requests, create_task/update_task, and the report tools' category cohorts. Categories are usually few — the first page is normally all of them.",
 		inputSchema: ListTaskCategoriesInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListTaskCategories(api, args));
-	server.registerTool("list_saved_task_filters", {
+	registerTenantTool(server, api, "list_saved_task_filters", {
 		title: "List saved task views",
 		description: "List the user's saved task views/filters, showing each view's code AND the criteria it encodes (statuses, date range, users, teams, clients, categories, overdue/unassigned flags). Use when the user references a saved view by name ('run my Weekly Review', 'my compliance filter') — resolve the code here, then pass it as list_tasks' savedFilter. The echoed criteria also let you answer 'what does my Weekly Review view actually show?' without running it. Prefer menuOnly=true when guessing which view the user means — those are the ones they use daily.",
 		inputSchema: ListSavedTaskFiltersInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSavedTaskFilters(api, args));
-	server.registerTool("list_saved_client_filters", {
+	registerTenantTool(server, api, "list_saved_client_filters", {
 		title: "List saved client views",
 		description: "List the user's saved client views/filters, showing each view's code AND the criteria it encodes (statuses, client types, managers, partners, services, teams). Use when the user references a saved view by name ('my VAT clients view') — resolve the code here, then pass it as list_clients' savedFilter. Prefer menuOnly=true when guessing which view the user means.",
 		inputSchema: ListSavedClientFiltersInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSavedClientFilters(api, args));
-	server.registerTool("search_companies_house", {
+	registerTenantTool(server, api, "search_companies_house", {
 		title: "Search Companies House",
 		description: "Search the Companies House public register by company name (full or partial) or company number. Returns matches with number, status, type, incorporation date, and registered address — live data from the register, not limited to the practice's clients. Use for prospect due diligence ('look up Bristol Roofing'), finding a company number before get_companies_house_profile, or checking name availability. For an EXISTING client's company number, prefer get_client_summary (business details) over searching by name.",
 		inputSchema: SearchCompaniesHouseInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleSearchCompaniesHouse(api, args));
-	server.registerTool("get_companies_house_profile", {
+	registerTenantTool(server, api, "get_companies_house_profile", {
 		title: "Get a company's full Companies House profile",
 		description: "Get the live Companies House record for one company number: legal status, incorporation date, registered office, SIC codes, accounts and confirmation-statement deadlines (with OVERDUE flags), last-filed accounts, charges/insolvency/liquidation flags, and current + resigned officers. Answers 'when are ACME's accounts due at Companies House?', 'who are the directors?', 'does this prospect have insolvency history?'. REQUIRES a company number — use search_companies_house for name lookups, or get_client_summary's business details for an existing client's number. Pass includeOfficers=false when only filing dates matter. Officers tolerate partial failure — the profile still returns if they can't be loaded.",
 		inputSchema: GetCompaniesHouseProfileInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetCompaniesHouseProfile(api, args));
-	server.registerTool("list_document_requests", {
+	registerTenantTool(server, api, "list_document_requests", {
 		title: "List / filter document requests to clients",
 		description: "List document requests across the practice (or one client) with status, client, manager/partner, task category, search, sort, and pagination. Each row shows status, deadline, documents requested, chase history (last chased / next chase), and the linked task. THE tool for 'what are we waiting on from clients?' (status=Open, sortBy=CreatedDate), 'has ACME sent their records?' (clientCode), 'what's submitted and needs review?' (status=Submitted), 'how many open requests?' (limit=0). Statuses: Draft (not sent) → Open (waiting on client) → Submitted (client responded, awaiting review) → Accepted/Rejected. For aggregate response-time analytics use get_client_responsiveness_report instead; this is the item-level view.",
 		inputSchema: ListDocumentRequestsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListDocumentRequests(api, args));
-	server.registerTool("list_data_form_requests", {
+	registerTenantTool(server, api, "list_data_form_requests", {
 		title: "List / filter data form (questionnaire) requests",
 		description: "List data-form (questionnaire) requests sent to clients — e.g. Self Assessment questionnaires, onboarding forms — with status, client, form, category, manager/partner, search, sort, and pagination. Each row shows status, sent/submitted dates, answers awaiting review, and chase history. Answers 'who still hasn't returned the SA questionnaire?' (formCode + status=PendingResponse), 'which form responses need reviewing?' (status=ResponseReceived — check pendingReviewCount per row), 'what forms has ACME been sent?' (clientCode). Statuses: PendingResponse (waiting on client) / ResponseReceived (submitted; answers may still need review).",
 		inputSchema: ListDataFormRequestsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListDataFormRequests(api, args));
-	server.registerTool("list_time_entries", {
+	registerTenantTool(server, api, "list_time_entries", {
 		title: "List / filter time entries",
 		description: "List recorded time entries with filters: team member, client, task, preset date range (or CustomDateRange + fromDate/toDate), billable flag, billed flag, search, sort, pagination. Answers 'how much time have I logged this week?' (userCode = current user, dateRange=ThisWeek), 'time spent on ACME this month' (clientCode + dateRange=ThisMonth), 'what unbilled time do we have?' (isBillable=true, isBilled=false — the WIP question), 'biggest time entries on this job' (taskItemCode, sortBy=DurationMinutes, sortDesc=true). Each page also shows its summed duration. IMPORTANT: prefer a narrow dateRange — unwindowed queries scan all history. For 'how many entries?' pass limit=0. For aggregate per-service/per-client totals over a period prefer get_service_time_report — it sums the whole window in one call instead of paging entries.",
 		inputSchema: ListTimeEntriesInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListTimeEntries(api, args));
-	server.registerTool("get_service_time_report", {
+	registerTenantTool(server, api, "get_service_time_report", {
 		title: "Service time report — where recorded time goes",
 		description: "Where does the practice's recorded time actually go? Aggregates time entries in the window: summary KPIs (total / billable / attributed / unattributed minutes, entry count) plus a breakdown by billable service — or, when serviceCode is passed, by CLIENT within that one service. Rows include estimate-vs-actual variance where estimates exist. Answers 'where did our time go last month?', 'which services are over their estimates?', 'which clients consume the most bookkeeping time?' (serviceCode for the bookkeeping service). Cohort = time entries whose entry date falls in the window (default Last30Days). For individual entries use list_time_entries; for workload/throughput by person use get_team_workload_report. Constraints: dateRange='CustomDateRange' requires both startDate and endDate.",
 		inputSchema: GetServiceTimeReportInputSchema,
 		annotations: reportAnnotations
 	}, (args) => handleGetServiceTimeReport(api, args));
-	server.registerTool("list_recurring_tasks", {
+	registerTenantTool(server, api, "list_recurring_tasks", {
 		title: "List / filter recurring task templates",
 		description: "List the recurring-task templates that generate the practice's repeating work (monthly bookkeeping, quarterly VAT returns, annual accounts). Filters: active status, billable service, client, category, workflow, search, sort (Name / NextRunDate), pagination. Each row shows the recurrence pattern, linked service/workflow, assignee, and next run date. Answers 'what recurring work do we run?' (isActive=true), 'what recurring tasks does ACME have?' (clientCode), 'what generates next week?' (sortBy=NextRunDate), 'which recurring tasks use the VAT workflow?' (workflowCode from list_workflows). This lists the TEMPLATES — for the generated task instances use list_tasks with its recurring-task filter.",
 		inputSchema: ListRecurringTasksInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListRecurringTasks(api, args));
-	server.registerTool("list_sent_emails", {
+	registerTenantTool(server, api, "list_sent_emails", {
 		title: "List emails Sodium sent (delivery audit trail)",
 		description: "List the emails Sodium sent on the practice's behalf — proposal/engagement emails, document-request chases, portal invitations, broadcasts — with delivery status (Queued/Processing/Sent/Failed/Cancelled), recipient, subject, date window, search, sort, pagination. THE tool for 'did the proposal email to ACME actually go out?', 'which emails failed this week?' (status=Failed + fromDate), 'what chases went to John?' (search on his address). This is the OUTBOUND SYSTEM audit trail only — for two-way email correspondence with a client (their replies, ad-hoc emails) use list_client_emails instead. Prefer a fromDate/toDate window; pass limit=0 for count-only. Follow up with get_sent_email for full recipient/error detail.",
 		inputSchema: ListSentEmailsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListSentEmails(api, args));
-	server.registerTool("get_sent_email", {
+	registerTenantTool(server, api, "get_sent_email", {
 		title: "Get one sent email's delivery detail",
 		description: "Get the full delivery record of one system-sent email by id (from list_sent_emails): sender, all to/cc/bcc recipients, created/processed/sent timeline, retry count, last error, and attachment names. Use to diagnose 'why didn't the client get the engagement letter email?'. Note: the email BODY is not retained in the send history — only the delivery record; don't promise the user the content.",
 		inputSchema: GetSentEmailInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetSentEmail(api, args));
-	server.registerTool("list_client_emails", {
+	registerTenantTool(server, api, "list_client_emails", {
 		title: "List a client's email correspondence (synced mailbox)",
 		description: "List email threads with one client from the practice's connected/synced mailbox: subject, latest sender, snippet, message and unread counts, attachments flag. Filters: search, direction (Inbound = from the client, Outbound = from the practice), provider folder, mailbox config, sort (default LatestMessageDate — pass sortDesc=true for newest first), pagination. Answers 'what's the latest correspondence with ACME?', 'has ACME replied about the VAT return?' (search), 'unanswered inbound email from clients'. Requires the practice to have connected a mailbox in Sodium — an empty result usually means no mailbox is synced, so say that rather than 'no emails exist'. For the delivery status of emails SODIUM sent (proposals, chases), use list_sent_emails instead.",
 		inputSchema: ListClientEmailsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListClientEmails(api, args));
-	server.registerTool("list_aml_clients", {
+	registerTenantTool(server, api, "list_aml_clients", {
 		title: "List AML / identity-check records",
 		description: "List the practice's AML (anti-money-laundering / KYC) records: each row shows the AML record id, whether it's an individual or entity, AML status (Active/Pending/Archived), risk level (Low/Normal/High), and how many linked contacts still have incomplete checks. AML records are held separately from PM client records — resolve by name with search (e.g. the client's name from list_clients). Answers 'which clients have outstanding AML checks?', 'do we have an AML record for ACME?', 'list our high-risk AML clients' (scan riskLevel in the output). Read-only — verifications are performed in the AML provider, not through this integration. Follow up with get_aml_client for per-contact statuses and risk assessments.",
 		inputSchema: ListAmlClientsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListAmlClients(api, args));
-	server.registerTool("get_aml_client", {
+	registerTenantTool(server, api, "get_aml_client", {
 		title: "Get one AML record's full status",
 		description: "Get one AML record by id (from list_aml_clients — NOT a PM client code): the record's status and risk level, every linked contact with their onboarding status and AML check status (NotStarted/InProgress/Ready/InReview/Complete/ActionRequired/Cancelled), and the risk-assessment history (status, risk level, who prepared/reviewed, notes). Answers 'is ACME's AML complete?', 'which directors still need ID checks?', 'when was the last risk assessment reviewed and by whom?'. Perfect for onboarding-readiness checks: pair with get_client_summary and list_document_requests for a full 'are we ready to act for this client?' picture. Risk assessments tolerate partial failure — the record still returns with a note.",
 		inputSchema: GetAmlClientInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetAmlClient(api, args));
-	server.registerTool("list_billing_line_items", {
+	registerTenantTool(server, api, "list_billing_line_items", {
 		title: "List / filter billing line items",
 		description: "List the billing line items Sodium has generated from client service subscriptions: status (Pending = awaiting approval, Approved = ready to invoice, Invoiced = pushed to the accounting system, Cancelled), client, service, billing-date window, sort, pagination. Each row shows value (quantity × unit price), VAT rate, billing period, and description; each page shows its summed net value. Answers 'what's waiting to be billed?' (status=Pending), 'what are we billing ACME this month?' (clientCode + billingDateFrom/To), 'how much bookkeeping revenue is queued?' (billableServiceCode + status filters), 'biggest pending lines' (sortBy=UnitPrice, sortDesc=true). For UNBILLED TIME (WIP) use list_time_entries with isBillable=true + isBilled=false — this tool is the service-subscription billing pipeline, not timesheets.",
 		inputSchema: ListBillingLineItemsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListBillingLineItems(api, args));
-	server.registerTool("get_practice_dashboard", {
+	registerTenantTool(server, api, "get_practice_dashboard", {
 		title: "Practice dashboard — state of the practice right now",
 		description: "One-call snapshot of what needs attention across the whole practice: overdue task count, tasks due in the next 7 days, blocked tasks, open document requests and pending data forms (what clients are sitting on), unassigned actionable workflow steps, total unbilled time, and the open proposal pipeline value. THE opening move for 'give me my morning briefing', 'what needs attention?', 'how are we doing?' — each non-zero line names the drill-down tool and filters to investigate it. Composed from count-only queries so it's cheap; sections tolerate partial failure independently. Takes no parameters.",
 		inputSchema: GetPracticeDashboardInputSchema,
 		annotations: lookupAnnotations
 	}, () => handleGetPracticeDashboard(api));
-	server.registerTool("get_onboarding_status", {
+	registerTenantTool(server, api, "get_onboarding_status", {
 		title: "Onboarding readiness check for one client",
 		description: "Are we ready to act for this client? One call assembles: engagement status (accepted letter of engagement or not), AML record matched by name (per-contact check completeness), HMRC agent authorisation statuses (granted vs outstanding), open document requests and pending data forms, and key-data completeness (company number, UTR, VAT, PAYE). Use for 'are we ready to start for Bristol Roofing?', 'what's blocking ACME's onboarding?', or a pre-work compliance check on any client. AML matching is by client NAME — verify the matched record is right. Everything after the client fetch tolerates partial failure.",
 		inputSchema: GetOnboardingStatusInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetOnboardingStatus(api, args));
-	server.registerTool("list_pending_workflow_steps", {
+	registerTenantTool(server, api, "list_pending_workflow_steps", {
 		title: "List actionable workflow steps across the practice",
 		description: "Practice-wide list of workflow steps that are actionable RIGHT NOW — the step-level 'what should I do next?'. Filters: assigned user ('my steps' — use the current user's code), assigned team, isUnassigned (work nobody owns; OR-combines with assignedUserCode), step type (Standard = internal work; DocumentRequest/DocumentApproval/ClientConfirmation/SendDataForm = client-facing), client, manager, partner, task category, search, sort (Deadline for urgency), pagination. Each row carries the task/group/step numbers that get_task_context and update_workflow_step need. Answers 'what steps are waiting on me?', 'what's unassigned?', 'which client-confirmation steps are outstanding?'. Pass limit=0 for count-only.",
 		inputSchema: ListPendingWorkflowStepsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListPendingWorkflowSteps(api, args));
-	server.registerTool("get_client_agent_authorisations", {
+	registerTenantTool(server, api, "get_client_agent_authorisations", {
 		title: "Get a client's HMRC agent authorisation statuses",
 		description: "Per-tax-regime HMRC agent authorisation status for one client (Self Assessment, Corporation Tax, PAYE, VAT, CIS, MTD variants...): NotRequested / Requested / Granted, whether each is required by the client's services, and any in-flight HMRC invitation with its expiry. Answers 'do we have SA authorisation for ACME?', 'which authorisations are missing before we can file?'. Read-only — requesting authorisations is done from the client's page in Sodium. Records only appear once the client has services that require them; an empty result on a new client is normal.",
 		inputSchema: GetClientAgentAuthorisationsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetClientAgentAuthorisations(api, args));
-	server.registerTool("list_unbilled_time_clients", {
+	registerTenantTool(server, api, "list_unbilled_time_clients", {
 		title: "Unbilled time totals per client (WIP recovery)",
 		description: "The WIP-recovery aggregate: billable-but-unbilled time summed PER CLIENT by the API — one call answers 'which clients have unbilled time and how much?'. Optional name search and pagination (default 25/page). THE tool for 'what unbilled time do we have?', 'how much WIP is sitting on ACME?' (search), 'where's our biggest billing leak?'. Drill into one client's individual entries with list_time_entries (clientCode + isBillable=true + isBilled=false); actually billing the time is done from Sodium's Time screen. Pass limit=0 for count-only.",
 		inputSchema: ListUnbilledTimeClientsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListUnbilledTimeClients(api, args));
-	server.registerTool("get_engagement_pipeline_summary", {
+	registerTenantTool(server, api, "get_engagement_pipeline_summary", {
 		title: "Proposal pipeline totals (counts + values by status)",
 		description: "One-call aggregate of the engagement pipeline: counts and total values for Unsent / Sent / Viewed / Accepted / Rejected, plus the open pipeline (sent + viewed awaiting a decision). Answers 'what's our proposal pipeline worth?', 'how much did we win this quarter?' (dateRange=ThisQuarter, read the Accepted line), 'how much value is sitting unsigned?'. Omit the window for the all-time picture. Much cheaper than paging list_proposals and adding up — prefer this for any totals question; use list_proposals for the individual engagements. Constraints: dateRange='CustomDateRange' requires dateFrom and dateTo.",
 		inputSchema: GetEngagementPipelineSummaryInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetEngagementPipelineSummary(api, args));
-	server.registerTool("list_client_documents", {
+	registerTenantTool(server, api, "list_client_documents", {
 		title: "List / search the document register",
 		description: "List documents held against clients (metadata only — titles, files, statuses; no file contents): filter by client, search (3+ chars), practice review status ('PendingReview' = uploads awaiting review), client approval status ('Pending' = sent to the client for sign-off, e.g. draft accounts), category, manager/partner, task category, sort, pagination. Answers 'do we have ACME's signed engagement letter?' (clientCode + search), 'which uploads need reviewing?' (reviewStatus=PendingReview), 'what's awaiting client approval?' (clientApprovalStatus=Pending). Files themselves are opened in Sodium or the portal — don't promise content extraction. Pass limit=0 for count-only.",
 		inputSchema: ListClientDocumentsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListClientDocuments(api, args));
-	server.registerTool("list_data_forms", {
+	registerTenantTool(server, api, "list_data_forms", {
 		title: "List data form (questionnaire) templates",
 		description: "List the practice's data-form TEMPLATES — the questionnaires it can send to clients (SA questionnaire, onboarding forms...). Filters: search, status ('Published' = sendable, the usual filter), sort, pagination. This resolves 'the SA questionnaire' to the formCode that list_data_form_requests filters on and send_data_form requires. Each row shows category and total response count. For who's been SENT a form and who's responded, use list_data_form_requests.",
 		inputSchema: ListDataFormsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListDataForms(api, args));
-	server.registerTool("get_task_history", {
+	registerTenantTool(server, api, "get_task_history", {
 		title: "Get a task's change history (audit trail)",
 		description: "The full audit trail of one task, oldest first: creation, task status changes, reassignments, and workflow-step status/assignee transitions — each attributed to the team member, the client (via portal or magic link), or the system. Answers 'who changed the due date?', 'when did this move to InProgress and who did it?', 'did the client action their step themselves?'. Complements get_task_context (current state) with how it got there.",
 		inputSchema: GetTaskHistoryInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetTaskHistory(api, args));
-	server.registerTool("list_invoice_submissions", {
+	registerTenantTool(server, api, "list_invoice_submissions", {
 		title: "List invoice submissions to the accounting system",
 		description: "The invoice hand-off after list_billing_line_items: batches of billing lines submitted (or queued/failed/projected) to the connected accounting system, with external invoice numbers and links. Filters: status ('Failed' = didn't reach the accounting system, the actionable one; 'Projected' = forecast only), client, billing-date window, sort (TotalAmount for biggest first), pagination. Answers 'did ACME's invoice go through to Xero?', 'which invoice submissions failed and why?', 'what invoicing is forecast next month?' (status=Projected + window). Retrying failures is done in the Sodium UI. Pass limit=0 for count-only.",
 		inputSchema: ListInvoiceSubmissionsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListInvoiceSubmissions(api, args));
-	server.registerTool("list_service_packages", {
+	registerTenantTool(server, api, "list_service_packages", {
 		title: "List service packages (bundled offerings)",
 		description: "List the practice's service packages — bundled offerings like a 'Growth package' — with contents (which services at which frequency), pricing mode (single package price vs per-service), and approximate annual value. Filters: search, contains-service (billableServiceCode array — 'which packages include bookkeeping?'), pagination. Complements list_services (individual catalogue). Applying a package to a client is done in the Sodium UI.",
 		inputSchema: ListServicePackagesInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListServicePackages(api, args));
-	server.registerTool("list_portal_users", {
+	registerTenantTool(server, api, "list_portal_users", {
 		title: "List client portal users and their login activity",
 		description: "Portal-access audit: every client-portal login (linked contact, email, active/deactivated, email-verified) with last-login date and invitation date. Filters (applied client-side — the endpoint returns everyone): activeOnly, neverLoggedIn ('who was invited but never logged in?' — the portal-adoption question). Answers 'which clients actually use the portal?', 'who needs a fresh invitation?'. Managing access and resending invitations is done from the client's contacts in Sodium.",
 		inputSchema: ListPortalUsersInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListPortalUsers(api, args));
-	server.registerTool("list_email_broadcasts", {
+	registerTenantTool(server, api, "list_email_broadcasts", {
 		title: "List email broadcasts (campaigns)",
 		description: "List the practice's email broadcasts/campaigns with status (Draft/Queued/Sending/Completed/Failed/Cancelled), subject, audience, and progress counters (processed/total clients, failures). Answers 'what have we broadcast recently?', 'did the MTD newsletter finish sending?'. Read-only — creating and sending broadcasts stays in the Sodium UI. Follow up with get_email_broadcast for per-client delivery results.",
 		inputSchema: ListEmailBroadcastsInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListEmailBroadcasts(api, args));
-	server.registerTool("get_email_broadcast", {
+	registerTenantTool(server, api, "get_email_broadcast", {
 		title: "Get one broadcast's detail and delivery results",
 		description: "One campaign in full: configuration (subject, audience definition), progress counters, and per-client delivery rows — Sent / Failed / Skipped with the reason for each failure or skip. Answers 'how did the newsletter do — who didn't get it and why?'. Requires the broadcast code from list_email_broadcasts. Recipient rows are paged (recipientsLimit/recipientsOffset, default 25); pass recipientsLimit=0 for campaign detail only.",
 		inputSchema: GetEmailBroadcastInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetEmailBroadcast(api, args));
-	server.registerTool("get_client_email_thread", {
+	registerTenantTool(server, api, "get_client_email_thread", {
 		title: "Read one email conversation (synced mailbox)",
 		description: "Drill into one email thread from the synced mailbox: every message in order with date, sender, read/attachment flags, and preview text, plus which clients and tasks the thread is linked to. Requires configCode AND conversationId — both shown per thread in list_client_emails output; never guess them. Answers 'what did ACME actually say in that thread?', 'show me the whole conversation about the VAT surcharge'. Message previews are snippets, not complete bodies — full bodies and attachments are opened in Sodium.",
 		inputSchema: GetClientEmailThreadInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleGetClientEmailThread(api, args));
-	server.registerTool("list_client_links", {
+	registerTenantTool(server, api, "list_client_links", {
 		title: "List the URLs saved on a client",
 		description: "The links saved against a client record — website, LinkedIn, accounting-software link, shared folder, etc. Answers 'what's ACME's website?', 'do we have a Xero link for Greggs?'. These are saved bookmarks, NOT related-client relationships. Small list, no filters needed beyond the client code.",
 		inputSchema: ListClientLinksInputSchema,
 		annotations: lookupAnnotations
 	}, (args) => handleListClientLinks(api, args));
-	registerWriteTool(server, config.context, "add_client_service", {
+	registerWriteTool(server, api, config.context, "add_client_service", {
 		title: "Assign a catalogue service to a client",
 		description: "Put a client on one of the practice's services: requires billableServiceCode (from list_services), billingFrequency (must match one of the service's configured pricing options — check get_service_details first), and startDate. Optional: status (default Active; use 'Proposed' when quoting), custom price (with overridePricing=true), pricing tier (REQUIRED for CustomTiers-priced services), setup fee, managing user, initial stage, auto-invoicing and first billing date. Use for 'put ACME on monthly bookkeeping', 'add VAT returns to Greggs from next month'. NOT exposed: pricing-factor questionnaires — services priced by factors should be configured in the Sodium UI; if the API rejects the call asking for pricing answers, say so and point the user to the UI. Check get_client_summary first to avoid assigning a duplicate service.",
 		inputSchema: AddClientServiceInputSchema,
@@ -9270,7 +9270,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddClientService(api, args));
-	registerWriteTool(server, config.context, "update_client_service_stage", {
+	registerWriteTool(server, api, config.context, "update_client_service_stage", {
 		title: "Move a client's service to a different stage (kanban)",
 		description: "Move one client-service card to a different workflow stage — the kanban move, from chat. Requires the client code, the client's service-subscription code (from get_client_summary's services section — NOT the catalogue service code), and the target stageCode (stage codes are in get_service_details for the underlying service). Pass stageCode=null to clear the stage. Use for 'move ACME's VAT return to Records In', 'mark the bookkeeping as Finished on the board'. Note: workflows can also set stages automatically via SetServiceStage steps — a manual move may be overridden by the next automated step.",
 		inputSchema: UpdateClientServiceStageInputSchema,
@@ -9281,7 +9281,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateClientServiceStage(api, args));
-	registerWriteTool(server, config.context, "create_document_request", {
+	registerWriteTool(server, api, config.context, "create_document_request", {
 		title: "Draft a document request for a client",
 		description: "Create a document request as a DRAFT — nothing is sent and the client is not notified. Requires clientCode and a title; optional client-facing description (write it as the client will read it), deadline, and a team member to notify on submission. Use for 'ask ACME for their year-end records', 'request the Jan–Mar bank statements from Greggs'. The user reviews and sends it from the client's Documents tab in Sodium — ALWAYS tell them it's drafted, not sent. Track it afterwards with list_document_requests (status=Draft).",
 		inputSchema: CreateDocumentRequestInputSchema,
@@ -9292,7 +9292,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateDocumentRequest(api, args));
-	registerWriteTool(server, config.context, "send_data_form", {
+	registerWriteTool(server, api, config.context, "send_data_form", {
 		title: "Send a data form (questionnaire) to a client",
 		description: "Send a published data form to a client. ⚠ SENDS IMMEDIATELY — an email goes to the client the moment this is called; there is no draft state. NEVER call this without the user explicitly confirming the send in this conversation (form + client + recipients). Requires formCode (from list_data_forms) and clientCode. Optional: client-facing message, recipient contact types or explicit addresses (only addresses the user gave or that are on the client's contacts), team member to notify on submission, autoAcceptData (default false — answers await review; only enable when explicitly asked), chase-frequency override. Confirm before calling; afterwards report exactly who it was sent to. Track responses with list_data_form_requests.",
 		inputSchema: SendDataFormInputSchema,
@@ -9303,7 +9303,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleSendDataForm(api, args));
-	registerWriteTool(server, config.context, "create_proposal", {
+	registerWriteTool(server, api, config.context, "create_proposal", {
 		title: "Draft a proposal / letter of engagement",
 		description: "Create an engagement in UNSENT (draft) state — the client is NOT emailed; sending is a deliberate separate action in the Sodium UI. Requires clientCode and date. type defaults to ProposalAndEngagementLetter ('EngagementLetter' for existing clients needing only the letter). clientBillableServiceCodes are the CLIENT'S service-subscription codes (get_client_summary's services section), not catalogue codes — to propose a service the client doesn't have yet, first add_client_service with status 'Proposed', then include its new code here. Recipient defaults to the client's main contact when omitted; only use an email from the client's contacts or given by the user. Use for 'draft a proposal for Bristol Roofing covering bookkeeping and VAT'. Always report the drafted value and that it has NOT been sent; full detail via get_proposal_summary.",
 		inputSchema: CreateProposalInputSchema,
@@ -9314,7 +9314,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateProposal(api, args));
-	registerWriteTool(server, config.context, "update_client_dates", {
+	registerWriteTool(server, api, config.context, "update_client_dates", {
 		title: "Set key/statutory dates on a client",
 		description: "Set one or more of a client's key dates (year-end, VAT return due, PAYE/CIS filing due, pension re-enrolment...). Takes an array of { dateType, date } — only the types you pass change; pass date=null to clear one. Current values are in get_client_summary's key-dates section. Use for 'set ACME's year-end to 31 March', 'record the pension re-enrolment date'. CAUTION: for clients connected to Companies House, register-derived dates (accounts due, confirmation statement) are synced automatically and manual values may be overwritten — prefer setting only non-CH dates (YearEnd, VAT, PAYE, pension) on connected clients, and say so if asked to set a CH-derived one.",
 		inputSchema: UpdateClientDatesInputSchema,
@@ -9325,7 +9325,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateClientDates(api, args));
-	registerWriteTool(server, config.context, "update_client_business_details", {
+	registerWriteTool(server, api, config.context, "update_client_business_details", {
 		title: "Update a client's business/tax details",
 		description: "Update business details on a client: trading name, postal/invoice addresses, date of trading, nature of business, UTR, PAYE reference, Accounts Office reference, and VAT registration (registered flag, number, registration date, scheme, reporting period). Only the fields you pass change — the handler fetches current details and merges, and Companies-House-derived registration data (company number, incorporation date, registered address) is never touched. Pass null to clear a clearable field. Use for 'set ACME's UTR to 1234567890', 'mark Greggs as VAT registered on the flat rate scheme, quarterly Jan/Apr/Jul/Oct'. Current values are in get_client_summary's business details.",
 		inputSchema: UpdateClientBusinessDetailsInputSchema,
@@ -9336,7 +9336,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateClientBusinessDetails(api, args));
-	registerWriteTool(server, config.context, "create_saved_task_filter", {
+	registerWriteTool(server, api, config.context, "create_saved_task_filter", {
 		title: "Save a task query as a reusable view",
 		description: "Persist a task filter as a saved view the user can reopen in Sodium and rerun here (list_tasks savedFilter). The natural closer after building a filtered list in conversation — 'save that as a view called Monday Review'. Requires a name; accepts the full task-filter surface (statuses, date range + basis, users/teams/clients/categories/recurring templates, overdue/unassigned flags, projected/agenda modes, default sort). includeInMenu pins it to the user's menu; isShared makes it practice-visible (read-only to others) — both default off, only set when asked. Echo back the criteria you saved so the user can confirm they match intent.",
 		inputSchema: CreateSavedTaskFilterInputSchema,
@@ -9347,7 +9347,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateSavedTaskFilter(api, args));
-	registerWriteTool(server, config.context, "update_workflow_step", {
+	registerWriteTool(server, api, config.context, "update_workflow_step", {
 		title: "Update a workflow step (complete, skip, block, reassign)",
 		description: "Update one workflow step on a task: set status (Completed / Skipped / InProgress / Blocked with a blockedReason) and/or reassign to a user or team. Identify the step by taskCode + groupNumber + stepNumber exactly as shown in get_task_context's workflow section — ALWAYS call get_task_context first to confirm the numbers and current status. Use for 'mark the review step on TSK-123 as done', 'skip the client-approval step, they confirmed by phone', 'assign the bookkeeping steps to Jane'. Constraints: steps with dependencies may be rejected until prior steps complete — report the API's reason rather than retrying; auto-executing steps (emails, document requests) fire when their turn comes, so completing them manually may skip the automated action — warn the user if get_task_context showed the step as auto-executing. Step content/configuration is not editable here — that's done in the Sodium UI.",
 		inputSchema: UpdateWorkflowStepInputSchema,
@@ -9358,7 +9358,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateWorkflowStep(api, args));
-	registerWriteTool(server, config.context, "create_task", {
+	registerWriteTool(server, api, config.context, "create_task", {
 		title: "Create a new task",
 		description: "Create a one-off task. Requires name, startDate, and dueDate (YYYY-MM-DD — 'due Friday' resolves against today from the startup context). Optional: description, status (defaults NotStarted), statutory due date, time estimate, client(s) (codes from list_clients), assignee (user code from the roster/list_users, or team code from list_teams), linked client-billable-service, category (list_task_categories), and a checklist (array of item texts). Use for 'create a task to chase ACME's rental schedule, due Friday', 'add a task for Jane to review the draft accounts'. Do NOT use for recurring schedules or workflow-driven tasks — those are set up in the Sodium UI. If the user gave a client or person by name, resolve codes first; ask rather than guess when multiple matches exist.",
 		inputSchema: CreateTaskInputSchema,
@@ -9369,7 +9369,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateTask(api, args));
-	registerWriteTool(server, config.context, "update_task", {
+	registerWriteTool(server, api, config.context, "update_task", {
 		title: "Update a task (status, dates, assignment, details)",
 		description: "Update fields on an existing task by code: status (mark Completed / InProgress / Blocked / Skipped), name, description, start/due/statutory dates, time estimate, assigned user or team, and category. Only the fields you pass change — the handler fetches the current task and preserves everything else (clients, checklist, service and recurring-task links), so it's safe to pass just { taskCode, status: 'Completed' } for 'mark it done'. Pass null to clear a clearable field (description, statutory date, estimate, assignee, team, category). Use for 'mark TSK-123 complete', 'push the deadline to Friday', 'reassign it to Jane' (resolve her code from the roster), 'unassign this task' (assignedUserCode=null). Completing a task does NOT complete its workflow steps — if get_task_context showed open steps, tell the user they remain open. Cannot delete tasks — deletion isn't available through the MCP.",
 		inputSchema: UpdateTaskInputSchema,
@@ -9380,7 +9380,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateTask(api, args));
-	registerWriteTool(server, config.context, "log_time_entry", {
+	registerWriteTool(server, api, config.context, "log_time_entry", {
 		title: "Log a time entry",
 		description: "Record time spent, after the fact. Requires entryDate (YYYY-MM-DD — use today from the startup context when the user doesn't say) and durationMinutes ('2 hours' → 120). Optional: description (strongly recommended — it feeds billing narratives), client code, task code, workflow group/step numbers (from get_task_context), billable flag, hourly rate, and userCode when logging on someone else's behalf (defaults to the authenticated user). Use for 'log 2 hours on ACME for today — reviewing the draft accounts', 'add 45 minutes against the Greggs VAT task'. Billable and rate default from practice/team-member configuration — only pass them when the user is explicit. Some practices require a client or task link; if the API rejects the entry saying so, ask the user which client/task to attach.",
 		inputSchema: LogTimeEntryInputSchema,
@@ -9391,7 +9391,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleLogTimeEntry(api, args));
-	registerWriteTool(server, config.context, "add_task_note", {
+	registerWriteTool(server, api, config.context, "add_task_note", {
 		title: "Add a note to a task",
 		description: "Create a new note on a task. Additive — does not modify or delete existing notes. The note is attributed to the authenticated API user (the current practice member) and timestamped to 'now'. Use this when the user asks you to capture something on a task: 'add a note on the Greggs year-end task that we're waiting on the rental schedule', 'log on the task that I called John today and got voicemail'. Notes can be pinned; only pin when the user explicitly asks for it. The user can always edit or delete notes in the Sodium UI if the wording isn't right.",
 		inputSchema: AddTaskNoteInputSchema,
@@ -9402,7 +9402,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddTaskNote(api, args));
-	registerWriteTool(server, config.context, "create_client", {
+	registerWriteTool(server, api, config.context, "create_client", {
 		title: "Create a new client",
 		description: "Create a new client record in the practice. Requires name and type (PrivateLimitedCompany, Individual, SoleTrader, etc.). Optionally set status (Active/Prospect/Inactive/LostProspect), email, telephone, internal reference, and assign a manager/partner/associate/team. The client code is auto-generated. Use when the user says 'add a new client', 'create client ACME Ltd', 'onboard a new prospect'.",
 		inputSchema: CreateClientInputSchema,
@@ -9413,7 +9413,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateClient(api, args));
-	registerWriteTool(server, config.context, "add_client_note", {
+	registerWriteTool(server, api, config.context, "add_client_note", {
 		title: "Add a note to a client",
 		description: "Create a new note on a client. Additive — does not modify or delete existing notes. The note is attributed to the authenticated API user and timestamped to 'now'. Use this when the user asks you to capture something on a client record: 'add a note on ACME that they mentioned expanding into Ireland', 'log on Greggs that they're switching bookkeeping software next quarter'. Client notes are the right place for persistent, client-level context; for task-specific notes use add_task_note. The user can edit or delete notes in the Sodium UI.",
 		inputSchema: AddClientNoteInputSchema,
@@ -9424,7 +9424,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleAddClientNote(api, args));
-	registerWriteTool(server, config.context, "update_client_custom_fields", {
+	registerWriteTool(server, api, config.context, "update_client_custom_fields", {
 		title: "Update custom field values on a client",
 		description: "Set or clear custom field values on a client. Accepts a map of field codes to values. Only fields included in the map are updated — omitted fields keep their current values. Pass null to clear a field. Field codes and current values are visible in the Custom Fields section of get_client_summary. Values are validated against the field's data type (Text, Number, Date, Boolean, Select, MultiSelect) before sending — invalid values return a validation error with guidance. Use this when the user says things like 'set the referral source on ACME to Google', 'update the fee review date for Smith & Co', 'clear the VAT scheme field on Greggs'. Multiple fields can be updated in a single call.",
 		inputSchema: SetClientCustomFieldsInputSchema,
@@ -9435,7 +9435,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleSetClientCustomFields(api, args));
-	registerWriteTool(server, config.context, "update_contact", {
+	registerWriteTool(server, api, config.context, "update_contact", {
 		title: "Update a contact's details",
 		description: "Update fields on an existing contact: name, email, phone, mobile, date of birth, UTR, NI number, address. The contact's lastName is always required (even if unchanged). Only include fields you want to change — but note the API replaces the entire contact record, so omitted optional fields may be cleared. To be safe, fetch the contact via list_contacts first, then pass all current values plus your changes. Use when the user says things like 'update John's email to ...', 'change the phone number for contact CON-001', 'set Jane's date of birth to ...'.",
 		inputSchema: UpdateContactInputSchema,
@@ -9446,7 +9446,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleUpdateContact(api, args));
-	registerWriteTool(server, config.context, "create_contact", {
+	registerWriteTool(server, api, config.context, "create_contact", {
 		title: "Create a new contact",
 		description: "Create a new contact record. Requires at least a last name. Optionally set title, first name, email, phone, mobile, date of birth, UTR, NI number, and address. The contact code is auto-generated. Use when the user says 'add a contact', 'create contact John Smith', 'add a new director for ACME'. Note: this creates the contact record only — to link it to a client, use the Sodium web UI.",
 		inputSchema: CreateContactInputSchema,
@@ -9457,7 +9457,7 @@ async function buildServer(config) {
 			openWorldHint: true
 		}
 	}, (args) => handleCreateContact(api, args));
-	registerWriteTool(server, config.context, "link_contact_to_client", {
+	registerWriteTool(server, api, config.context, "link_contact_to_client", {
 		title: "Link an existing contact to a client",
 		description: "Link an existing contact to a client with one or more relationship types (Main, Billing, Payroll, Accounts, Director, Psc). Optionally set a free-text role (e.g. 'Managing Director'). The contact must already exist — use create_contact first if needed, then link with this tool. Use when the user says 'add John as a director on ACME', 'link contact CON-001 to client CLI-002 as the main contact'.",
 		inputSchema: LinkContactToClientInputSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sodiumhq/mcp-pm",
-  "version": "0.1.0-beta.4445",
+  "version": "0.1.0-beta.4448",
   "description": "Sodium Practice Management MCP server — lets AI assistants interact with your Sodium tenant",
   "type": "module",
   "bin": {