@indemn/cli 1.5.0 → 1.7.0

package/dist/mcp/tools.js

@@ -1,66 +1,327 @@
 import { z } from 'zod/v3';
-import { AgentsSDK } from '../sdk/agents.js';
+import { AgentInsightsSDK, AgentsSDK } from '../sdk/agents.js';
+import { createAgentFromSkeleton, exportAgent, importAgent, missingSkeletonFields, parseModel, } from '../sdk/agent-bundle.js';
+import { getAskers } from '../core/scope.js';
+import { proposedSkills, skillConfiguration } from '../sdk/skills.js';
+import { VoiceSDK } from '../sdk/voice.js';
+import { DistributionSDK } from '../sdk/distribution.js';
+import { AnalyticsSDK, AuditSDK, OrgSettingsSDK } from '../sdk/analytics.js';
+import { TicketsSDK } from '../sdk/tickets.js';
+import { BillingSDK } from '../sdk/billing.js';
+import { CampaignsSDK } from '../sdk/campaigns.js';
+import { PlatformSDK } from '../sdk/platform.js';
+import { jarvisChat } from '../sdk/jarvis-chat.js';
+import { applyConfigChange, describePlan, liveText, mayBeLive, modelArg, planConfigChange } from '../sdk/config-change.js';
 import { ConfigSDK } from '../sdk/config.js';
 import { FunctionsSDK } from '../sdk/functions.js';
 import { KBSDK } from '../sdk/kb.js';
 import { RubricsSDK } from '../sdk/rubrics.js';
 import { TestSetsSDK } from '../sdk/test-sets.js';
-import { EvalSDK } from '../sdk/eval.js';
-import { ChatSession } from '../sdk/chat.js';
+import { EvalSDK, gateVerdict } from '../sdk/eval.js';
+import { exchange, openTestChat } from '../sdk/test-chat.js';
+import { ConversationsSDK, conversationToTestSet, conversationUrl, isCliConversation, isTestConversation, projectOfAgent } from '../sdk/conversations.js';
 import { exportEvalMarkdown, exportEvalReport, exportAgentCard } from '../report/export.js';
+import { createRegistry } from './registry.js';
+import { OrgsSDK } from '../sdk/orgs.js';
+import { whoami } from '../sdk/auth.js';
+import { NeedsInputError, SessionExpiredError } from '../core/runtime.js';
+// A REST skill's authentication as flat fields: for a nested object Gemini writes calls Google rejects.
+const skillAuthFields = {
+    auth_type: z.enum(['no-auth', 'api-key', 'basic-auth', 'bearer-token']).optional().describe('rest_api: how the API is called (default no-auth)'),
+    auth_token: z.string().optional().describe('bearer-token: the token'),
+    auth_key: z.string().optional().describe('api-key: the header name, e.g. x-api-key'),
+    auth_value: z.string().optional().describe('api-key: the key'),
+    auth_username: z.string().optional().describe('basic-auth: user name'),
+    auth_password: z.string().optional().describe('basic-auth: password'),
+};
+// Helper: the flat auth fields as the dashboard's skill form saves them (configurationSchema.authorization)
+function withAuthorization(args) {
+    if (!args.auth_type)
+        return args;
+    const fields = { 'api-key': ['key', 'value'], 'basic-auth': ['username', 'password'], 'bearer-token': ['token'], 'no-auth': [] };
+    const authorization = { type: args.auth_type };
+    for (const k of fields[args.auth_type] ?? []) {
+        const v = args[`auth_${k}`];
+        if (typeof v === 'string' && v)
+            authorization[k] = v;
+    }
+    return { ...args, configuration: { ...(args.configuration ?? {}), authorization } };
+}
 // Helper: format a successful MCP tool result
 function success(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
 // Helper: format an error MCP tool result
 function error(err) {
+    if (err instanceof NeedsInputError) {
+        return { content: [{ type: 'text', text: JSON.stringify({ needs_input: true, message: err.message, choices: err.choices, to_proceed: 'Ask the user which organization to use, then call again with org_id set to its id.' }, null, 2) }] };
+    }
     const message = err instanceof Error ? err.message : String(err);
     return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
 }
+// Helper: the org's pages in the dashboard, so the person gets a link instead of an id
+async function orgPages(client) {
+    const base = client.getHosts().copilot.replace(/\/api\/?$/, '');
+    return `${base}/#/organization/${await client.currentOrgId()}`;
+}
+// Test items and rubric rules as the evaluations service defines them (indemn_evals models).
+// Typed fields, not open records: models such as Gemini cannot fill an object with no
+// declared fields. Other fields the service accepts still pass through.
+// Test items and rubric rules with flat fields (a nested object makes Gemini write calls Google rejects);
+// mapped to the evaluations service's shape (inputs / expected, evaluation_criteria) before saving.
+const testItemSchema = z.object({
+    type: z.enum(['single_turn', 'scenario', 'voice_simulation', 'transcript']).describe('single_turn: one message; scenario: a simulated chat; voice_simulation: a simulated phone call'),
+    name: z.string().describe('Short name of what is tested'),
+    message: z.string().optional().describe('single_turn: the message sent to the agent'),
+    persona: z.string().optional().describe('scenario / voice_simulation: who the simulated customer is'),
+    initial_message: z.string().optional().describe('scenario / voice_simulation: their first message'),
+    goal: z.string().optional().describe('voice_simulation: what the caller wants'),
+    max_turns: z.number().int().optional().describe('scenario / voice_simulation: turns before stopping (default 5)'),
+    success_criteria: z.array(z.string()).optional().describe('Plain-language checks that must all pass (needed)'),
+    expected_outcome: z.string().optional(),
+    tool_present: z.array(z.string()).optional().describe('Skills that must be used'),
+    tool_absent: z.array(z.string()).optional().describe('Skills that must not be used'),
+    tags: z.array(z.string()).optional(),
+    priority: z.string().optional(),
+}).passthrough();
+const rubricRuleSchema = z.object({
+    id: z.string().describe('Short rule id, e.g. STAYS_ON_TOPIC'),
+    name: z.string(),
+    severity: z.string().describe('high, medium or low'),
+    category: z.string().describe('e.g. response_quality, accuracy, safety'),
+    description: z.string(),
+    pass_conditions: z.array(z.string()).optional().describe('What passing looks like'),
+    fail_conditions: z.array(z.string()).optional().describe('What failing looks like'),
+}).passthrough();
+const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+// Helper: a flat test item in the service's shape; inputs / expected given as objects (other clients) are kept.
+function toTestItem(item) {
+    const { message, persona, initial_message, goal, max_turns, success_criteria, expected_outcome, tool_present, tool_absent, inputs, expected, ...rest } = item;
+    return {
+        ...rest,
+        inputs: { ...(inputs ?? {}), ...defined({ message, persona, initial_message, goal, max_turns }) },
+        expected: { ...(expected ?? {}), ...defined({ success_criteria, expected_outcome, tool_present, tool_absent }) },
+    };
+}
+// Helper: a flat rubric rule in the service's shape (evaluation_criteria).
+function toRubricRule(rule) {
+    const { pass_conditions, fail_conditions, evaluation_criteria, ...rest } = rule;
+    const criteria = { ...(evaluation_criteria ?? {}), ...defined({ pass_conditions, fail_conditions }) };
+    return Object.keys(criteria).length ? { ...rest, evaluation_criteria: criteria } : rest;
+}
+// Objects whose fields a model cannot see (Gemini) arrive as JSON text: accept both.
+const parseJsonText = (v) => {
+    if (typeof v !== 'string')
+        return v;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+};
+const jsonObject = () => z.preprocess(parseJsonText, z.record(z.any()));
+// A skill for bulk_create_skills with flat fields (the configuration is built as create_function builds it);
+// a proposal from generate_skills_from_doc keeps its own configurationSchema.
+const skillDefinition = z.preprocess(parseJsonText, z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    type: z.string().describe('e.g. rest_api, transfer_call'),
+    url: z.string().optional().describe('rest_api: endpoint URL; {{parameter}} placeholders allowed'),
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional().describe('rest_api'),
+    payload: z.string().optional().describe('rest_api: request body as JSON text with {{parameter}} placeholders'),
+    ...skillAuthFields,
+    response_field: z.string().optional().describe('rest_api: dot-path of the answer to use'),
+    output_instructions: z.string().optional().describe('What the agent says with the answer'),
+    transfer_to: z.string().optional().describe('transfer_call: phone number (E.164) or SIP address'),
+    parameters: z.array(z.object({
+        name: z.string(), type: z.string().describe('string, number, boolean or list'),
+        description: z.string().optional(), required: z.boolean().optional(),
+    }).passthrough()).optional(),
+}).passthrough());
 export function registerTools(server, client) {
+    const reg = createRegistry(server, {
+        context: () => client.getResultContext(),
+        // Each call decides its own org; an answer given once is not reused for the next call.
+        resolveOrg: (explicit) => client.resolveOrg(explicit, { cache: false }),
+        // The person approves a change by names: look up the ids the call names.
+        // An id that names nothing gets no card: the registry answers "not found" instead.
+        displayNames: async (args, orgId) => {
+            const names = {};
+            const missing = [];
+            const notFound = /not found|is not on agent|404/i;
+            const add = (id, what, lookup) => typeof id === 'string' && id
+                ? lookup(id).then((x) => {
+                    if (typeof x?.name === 'string' && x.name)
+                        names[id] = x.name;
+                    else if (what && !x)
+                        missing.push(`${what} ${id}`);
+                }, (err) => { if (what && notFound.test(err instanceof Error ? err.message : String(err)))
+                    missing.push(`${what} ${id}`); })
+                : undefined;
+            await Promise.all([
+                add(args.agent_id ?? args.bot_id, 'agent', (id) => agents.getAgent(id)),
+                typeof args.agent_id === 'string' ? add(args.function_id, 'skill', (id) => skillOf(String(args.agent_id), id)) : undefined,
+                add(args.kb_id, 'knowledge base', (id) => kb.getKB(id)),
+                add(args.test_set_id, 'test set', (id) => testSets.getTestSet(id)),
+                add(args.rubric_id, 'rubric', (id) => rubrics.getRubric(id)),
+                add(orgId, null, (id) => client.copilotGet(`/organization/${id}`).then((r) => r.organization)),
+            ]);
+            return { names, missing };
+        },
+    });
+    const orgs = new OrgsSDK(client);
+    // ---------------------------------------------------------------------------
+    // Login and organization tools
+    // ---------------------------------------------------------------------------
+    reg.tool('whoami', 'Show the platform (dev or production), the logged-in user, the session expiry, the orgs you belong to, and whether this folder is linked to one org. Call this first when unsure which org to use.', {}, async () => {
+        try {
+            const info = whoami();
+            if (!info)
+                throw new SessionExpiredError('Not logged in. Run `indemn login` in a terminal.');
+            const link = client.getLink();
+            return success({ ...info, linked_folder: link ? { org_id: link.org_id, org_name: link.org_name, agents: link.agents, path: link.path } : null });
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_organizations', 'List the organizations you belong to on this platform. Pass one of these ids as org_id to other tools.', {}, async () => {
+        try {
+            return success(await orgs.listOrganizations());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_org_members', 'List the owners, admins and agents of an organization, with their roles.', {}, async () => {
+        try {
+            return success(await orgs.listMembers());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_channels', 'List the channels an agent can be published on, such as WEB or VOICE.', {}, async () => {
+        try {
+            return success(await orgs.listChannels());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
     const agents = new AgentsSDK(client);
     const config = new ConfigSDK(client);
     const functions = new FunctionsSDK(client);
+    // A skill of an agent by its id.
+    const skillOf = async (agentId, id) => {
+        const skill = (await functions.listFunctions(agentId)).find((f) => f._id === id);
+        if (!skill)
+            throw new Error(`Skill ${id} is not on agent ${agentId}.`);
+        return skill;
+    };
     const kb = new KBSDK(client);
     const rubrics = new RubricsSDK(client);
     const testSets = new TestSetsSDK(client);
     const evals = new EvalSDK(client);
+    // The evaluations service checks nothing about orgs: touch a rubric or test set only when its agent is in this org.
+    const rubricInOrg = async (id) => {
+        const r = await rubrics.getRubric(id);
+        if (r.agent_id)
+            await evals.assertAgentInOrg(String(r.agent_id));
+        return r;
+    };
+    const testSetInOrg = async (id) => {
+        const t = await testSets.getTestSet(id);
+        if (t.agent_id)
+            await evals.assertAgentInOrg(String(t.agent_id));
+        return t;
+    };
     // ---------------------------------------------------------------------------
     // Agent tools
     // ---------------------------------------------------------------------------
-    server.tool('list_agents', 'List all agents in the organization', { limit: z.number().optional().describe('Maximum number of agents to return') }, async (args) => {
+    reg.tool('list_agents', 'List the agents (bots) of the organization: id, name, channels. Start here to find an agent id.', { channel: z.string().optional().describe('Only agents on this channel, e.g. web, voice, email') }, async (args) => {
         try {
-            let result = await agents.listAgents();
-            if (args.limit)
-                result = result.slice(0, args.limit);
-            return success(result);
+            const pages = await orgPages(client);
+            const wanted = args.channel?.trim().toUpperCase();
+            // What a person needs, not the stored record (a page of full records ran to 73k characters).
+            const rows = (await agents.listAgents()).map((a) => ({
+                _id: a._id,
+                name: a.name,
+                ...(a.description ? { description: a.description } : {}),
+                // The list returns channel records, not the names the type declares.
+                channels: (a.channels ?? []).map((c) => (typeof c === 'string' ? c : c?.name ?? '')).filter(Boolean),
+                ...(a.connected_phone ? { phone: a.connected_phone } : {}),
+                updated_at: a.updatedAt,
+                url: `${pages}/ai-studio/bot/${a._id}/configurations`,
+            }));
+            return success(wanted ? rows.filter((a) => a.channels.some((c) => c.toUpperCase() === wanted)) : rows);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('get_agent', 'Get details of a specific agent', { agent_id: z.string().describe('The agent ID') }, async (args) => {
+    reg.tool('get_agent', 'Get one agent: name, description, channels and project. For what it does, use agent_summary; for its prompt and model, get_config.', { agent_id: z.string().describe('The agent ID') }, async (args) => {
         try {
             const result = await agents.getAgent(args.agent_id);
-            return success(result);
+            return success({ ...result, url: `${await orgPages(client)}/ai-studio/bot/${args.agent_id}/configurations` });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('create_agent', 'Create a new agent', {
-        name: z.string().describe('Agent name'),
-        channels: z.array(z.string()).optional().describe('Channels (e.g. ["WEB"])'),
+    reg.tool('create_agent', 'Create an agent with its basics: name, channels, what it is for, system prompt and model. Missing basics are asked from the user when the host can ask; otherwise the result lists them (pass minimal: true to create with only a name). Refuses a name that already exists in the org.', {
+        name: z.string().optional().describe('Agent name'),
+        channels: z.array(z.string()).optional().describe('Channels, e.g. ["WEB"] (see list_channels)'),
+        description: z.string().optional().describe('What the agent is for'),
+        system_prompt: z.string().optional().describe('System prompt'),
+        model: z.string().optional().describe('provider/model, e.g. openai/gpt-4.1 (see list_llm_models)'),
+        allow_duplicate: z.boolean().optional().describe('Create even if an agent with this name exists'),
+        minimal: z.boolean().optional().describe('Create with only the fields given, without asking for the rest'),
     }, async (args) => {
         try {
-            const result = await agents.createAgent({ name: args.name, channels: args.channels });
-            return success(result);
+            const skeleton = {
+                name: args.name ?? '',
+                channels: args.channels,
+                description: args.description,
+                system_prompt: args.system_prompt,
+                model: args.model ? parseModel(args.model) : undefined,
+            };
+            let missing = missingSkeletonFields(skeleton);
+            if (missing.length && !args.minimal) {
+                const titles = { name: 'Agent name', description: 'What is this agent for?', system_prompt: 'System prompt' };
+                const answers = await getAskers().form?.('Fill in the basics for the new agent.', missing.map((key) => ({ key, title: titles[key] ?? key, required: key === 'name' })));
+                if (answers) {
+                    if (answers.name)
+                        skeleton.name = answers.name;
+                    if (answers.description)
+                        skeleton.description = answers.description;
+                    if (answers.system_prompt)
+                        skeleton.system_prompt = answers.system_prompt;
+                }
+                missing = missingSkeletonFields(skeleton);
+                if (missing.includes('name') || (missing.length && !answers)) {
+                    throw new NeedsInputError(`Before creating the agent, provide: ${missing.join(', ')}. Or pass minimal: true to create it with only a name.`, missing.map((m) => ({ id: m, label: titles[m] ?? m })));
+                }
+            }
+            const result = await createAgentFromSkeleton(client, skeleton, { allowDuplicate: args.allow_duplicate });
+            return success({ agent: result.agent, set: result.set, not_set: missingSkeletonFields(skeleton) });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('update_agent', 'Update an existing agent', {
+    // Lifecycle lives on the V2 platform; "unknown" when it cannot be read (treated as published: mayBeLive).
+    const lifecycleOf = (id) => new AgentInsightsSDK(client).detail(id).then((d) => d.lifecycle ?? 'prototype', () => 'unknown');
+    // A change to an agent that may be live asks first; the approval names the fields, never their values (skill auth).
+    const liveChange = (what, skip) => ({
+        guardWhen: async (a) => mayBeLive(await lifecycleOf(String(a.agent_id))),
+        preview: async (a) => {
+            const fields = Object.keys(a).filter((k) => a[k] !== undefined && !['agent_id', 'confirm', 'org_id', ...skip].includes(k));
+            return `This will change ${what} of agent ${a.agent_id}: ${fields.join(', ') || 'nothing'}. The agent ${liveText(await lifecycleOf(String(a.agent_id)))}.`;
+        },
+    });
+    reg.tool('update_agent', 'Change an agent\'s name, description or webhook. For the prompt, greeting or model use set_config.', {
         agent_id: z.string().describe('The agent ID'),
         name: z.string().optional().describe('New agent name'),
         description: z.string().optional().describe('New agent description'),
@@ -81,20 +342,98 @@ export function registerTools(server, client) {
         catch (err) {
             return error(err);
         }
-    });
-    server.tool('delete_agent', 'Delete an agent', { agent_id: z.string().describe('The agent ID to delete') }, async (args) => {
+    }, liveChange('the name, description or webhook', []));
+    reg.tool('delete_agent', 'Delete an agent. It is removed from the dashboard and its knowledge base links are dropped.', {
+        agent_id: z.string().describe('The agent ID to delete'),
+        confirm_published: z.boolean().optional().describe('Required with confirm when the agent is published and the user explicitly agreed'),
+    }, async (args, meta) => {
         try {
+            const agent = await agents.getAgent(args.agent_id);
+            const lifecycle = await lifecycleOf(args.agent_id);
+            if (mayBeLive(lifecycle) && !meta.confirmedByPerson && args.confirm_published !== true) {
+                throw new Error(`"${agent.name}" ${liveText(lifecycle)}. Show the user; only if they explicitly agree, call again with confirm: true and confirm_published: true.`);
+            }
             await agents.deleteAgent(args.agent_id);
-            return success({ deleted: true, agent_id: args.agent_id });
+            return success({ deleted: true, agent_id: args.agent_id, name: agent.name });
         }
         catch (err) {
             return error(err);
         }
+    }, {
+        preview: async (a) => {
+            const agent = await agents.getAgent(String(a.agent_id));
+            const lifecycle = await lifecycleOf(String(a.agent_id));
+            return `This will delete agent "${agent.name}"${mayBeLive(lifecycle) ? `, which ${liveText(lifecycle)}` : ''}. It cannot be restored from the CLI.`;
+        },
     });
-    server.tool('clone_agent', 'Clone an existing agent', { agent_id: z.string().describe('The agent ID to clone') }, async (args) => {
+    const insights = new AgentInsightsSDK(client);
+    reg.tool('agent_summary', 'What an agent does: one paragraph (default) or its skills and knowledge sources (full: true). Read this before changing an agent.', { agent_id: z.string().describe('The agent ID'), full: z.boolean().optional().describe('List skills and knowledge sources') }, async (args) => {
         try {
-            const result = await agents.cloneAgent(args.agent_id);
-            return success(result);
+            return success(await insights.summary(args.agent_id, { text: !args.full }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('agent_stats', 'Conversation metrics for one agent (test conversations excluded). Dates are YYYY-MM-DD; default is the last 30 days.', {
+        agent_id: z.string().describe('The agent ID'),
+        date_from: z.string().optional().describe('YYYY-MM-DD'),
+        date_to: z.string().optional().describe('YYYY-MM-DD'),
+        channel: z.enum(['web', 'voice', 'all']).optional(),
+    }, async (args) => {
+        try {
+            return success(await insights.stats(args.agent_id, { from: args.date_from, to: args.date_to, channel: args.channel }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_agent_lifecycle', 'Move an agent between prototype, beta and published. Only the owner or an org admin may; the V2 platform enforces it.', { agent_id: z.string().describe('The agent ID'), lifecycle: z.enum(['prototype', 'beta', 'published']) }, async (args) => {
+        try {
+            return success(await insights.setLifecycle(args.agent_id, args.lifecycle));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('transfer_agent_owner', 'Make another user the owner of an agent. Only the current owner or an org admin may; the V2 platform enforces it.', { agent_id: z.string().describe('The agent ID'), owner_id: z.string().describe('User id of the new owner (see list_org_members)') }, async (args) => {
+        try {
+            return success(await insights.transferOwner(args.agent_id, args.owner_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('clone_agent', 'Copy an agent of this org into a new agent in the same org.', {
+        agent_id: z.string().describe('The agent ID to copy'),
+        name: z.string().optional().describe('Name of the copy'),
+        channels: z.array(z.string()).optional().describe('Channels of the copy'),
+    }, async (args) => {
+        try {
+            return success(await agents.cloneAgent(args.agent_id, { name: args.name, channels: args.channels }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('export_agent', 'Export an agent as a bundle: prompt, greeting, model, skills with parameters, linked knowledge base ids. Secrets in skill settings are redacted unless include_secrets is true.', { agent_id: z.string().describe('The agent ID'), include_secrets: z.boolean().optional() }, async (args) => {
+        try {
+            return success(await exportAgent(client, args.agent_id, { includeSecrets: args.include_secrets }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('import_agent', 'Create a new agent in this org from a bundle made by export_agent (possibly from another org or platform). Lists skills that failed and secrets to fill in.', {
+        bundle: z.record(z.unknown()).describe('The bundle returned by export_agent'),
+        name: z.string().optional().describe('Name for the new agent (default: the bundle name)'),
+        link_knowledge_bases: z.boolean().optional().describe('Link the same knowledge base ids if they exist in this org'),
+        allow_duplicate: z.boolean().optional(),
+    }, async (args) => {
+        try {
+            return success(await importAgent(client, args.bundle, {
+                name: args.name, linkKnowledgeBases: args.link_knowledge_bases, allowDuplicate: args.allow_duplicate,
+            }));
         }
         catch (err) {
             return error(err);
@@ -103,7 +442,7 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Config tools
     // ---------------------------------------------------------------------------
-    server.tool('get_config', 'Get the full configuration for an agent', { agent_id: z.string().describe('The agent ID') }, async (args) => {
+    reg.tool('get_config', 'An agent\'s configuration: system prompt, greeting (first message), LLM model and knowledge settings.', { agent_id: z.string().describe('The agent ID') }, async (args) => {
         try {
             const result = await config.getConfig(args.agent_id);
             return success(result);
@@ -112,25 +451,37 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('set_config', 'Update configuration for an agent', {
+    const applyChange = async (agentId, change, confirmedByPerson, confirmPublished) => {
+        const plan = await planConfigChange(client, agentId, change);
+        if (plan.changes.length === 0)
+            return success({ changed: [], message: 'Nothing to change: the agent already has these values.' });
+        if (mayBeLive(plan.lifecycle) && !confirmedByPerson && confirmPublished !== true) {
+            throw new NeedsInputError(`Agent ${agentId} ${liveText(plan.lifecycle)}. Show the user the change; only if they explicitly agree, call again with confirm: true and confirm_published: true.`);
+        }
+        const result = await applyConfigChange(client, plan, change);
+        return success({ changed: result.applied, not_saved: result.mismatched, lifecycle: plan.lifecycle });
+    };
+    const previewChange = (argsToChange) => async (a) => describePlan(await planConfigChange(client, String(a.agent_id), argsToChange(a)));
+    const configArgs = (a) => ({
+        system_prompt: a.system_prompt,
+        greeting: a.first_message,
+        model: a.model ? modelArg(String(a.model)) : undefined,
+    });
+    reg.tool('set_config', 'Change an agent\'s prompt, greeting and/or model. The confirmation shows the prompt diff and whether the agent is published; published agents need confirm_published too. The result says what was saved (read back from the platform).', {
         agent_id: z.string().describe('The agent ID'),
-        system_prompt: z.string().optional().describe('System prompt text'),
-        first_message: z.string().optional().describe('First message text shown to users'),
-    }, async (args) => {
+        system_prompt: z.string().optional().describe('New system prompt (whole text)'),
+        first_message: z.string().optional().describe('New greeting shown to users'),
+        model: z.string().optional().describe('provider/model, e.g. openai/gpt-4.1 (see list_llm_models)'),
+        confirm_published: z.boolean().optional().describe('Required with confirm when the agent is published and the user explicitly agreed'),
+    }, async (args, meta) => {
         try {
-            const input = {};
-            if (args.system_prompt !== undefined)
-                input.system_prompt = args.system_prompt;
-            if (args.first_message !== undefined)
-                input.first_message = { text: args.first_message };
-            const result = await config.setConfig(args.agent_id, input);
-            return success(result);
+            return await applyChange(args.agent_id, configArgs(args), meta.confirmedByPerson, args.confirm_published);
         }
         catch (err) {
             return error(err);
         }
-    });
-    server.tool('get_prompt', 'Get the system prompt for an agent', { agent_id: z.string().describe('The agent ID') }, async (args) => {
+    }, { preview: previewChange(configArgs) });
+    reg.tool('get_prompt', 'An agent\'s system prompt (the instructions it follows).', { agent_id: z.string().describe('The agent ID') }, async (args) => {
         try {
             const result = await config.getPrompt(args.agent_id);
             return success({ agent_id: args.agent_id, system_prompt: result ?? null });
@@ -139,22 +490,22 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('set_prompt', 'Set the system prompt for an agent', {
+    reg.tool('set_prompt', 'Replace an agent\'s system prompt. The confirmation shows the diff; published agents need confirm_published too.', {
         agent_id: z.string().describe('The agent ID'),
-        prompt: z.string().describe('The system prompt text'),
-    }, async (args) => {
+        prompt: z.string().describe('The whole new system prompt'),
+        confirm_published: z.boolean().optional().describe('Required with confirm when the agent is published and the user explicitly agreed'),
+    }, async (args, meta) => {
         try {
-            const result = await config.setPrompt(args.agent_id, args.prompt);
-            return success(result);
+            return await applyChange(args.agent_id, { system_prompt: args.prompt }, meta.confirmedByPerson, args.confirm_published);
         }
         catch (err) {
             return error(err);
         }
-    });
+    }, { preview: previewChange((a) => ({ system_prompt: String(a.prompt) })) });
     // ---------------------------------------------------------------------------
     // Function tools
     // ---------------------------------------------------------------------------
-    server.tool('list_functions', 'List all functions (tools) for an agent', { agent_id: z.string().describe('The agent ID') }, async (args) => {
+    reg.tool('list_functions', 'List an agent\'s skills (the actions it can take: REST calls, handoff, FAQ retriever, transfer call, ...), with their parameters.', { agent_id: z.string().describe('The agent ID') }, async (args) => {
         try {
             const result = await functions.listFunctions(args.agent_id);
             return success(result);
@@ -163,66 +514,130 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('create_function', 'Create a new function (tool) for an agent', {
+    reg.tool('create_function', 'Add a skill to an agent. rest_api skills need a configurationSchema (endpoint, method, auth, payload). Names too close to the built-in FAQ retriever are refused.', {
         agent_id: z.string().describe('The agent ID'),
         type: z.string().describe('Function type (e.g. "rest_api")'),
         description: z.string().optional().describe('What the function does'),
         name: z.string().optional().describe('Function name'),
-        url: z.string().optional().describe('Endpoint URL'),
-        method: z.string().optional().describe('HTTP method (GET, POST, etc.)'),
+        url: z.string().optional().describe('rest_api: endpoint URL'),
+        method: z.string().optional().describe('rest_api: HTTP method (GET, POST, etc.)'),
+        payload: z.union([z.string(), z.record(z.any())]).optional().describe('rest_api: request body (JSON); {{parameter}} placeholders are filled from the skill parameters'),
+        response_field: z.string().optional().describe('rest_api: dot-path of the response to use (e.g. data.result)'),
+        output_instructions: z.string().optional().describe('What the agent says with the answer; {{response.field}} reads the API answer'),
+        craft_response: z.boolean().optional().describe('true: the agent phrases the answer itself (default for rest_api without output_instructions); false: the answer, or output_instructions, goes to the customer as is'),
+        ...skillAuthFields,
+        configuration: jsonObject().optional().describe('Other configurationSchema fields (an object, or JSON text); the fields above win'),
+        transfer_to: z.string().optional().describe('transfer_call: phone number (E.164, e.g. +15551234567) or SIP address (sip:...) calls are transferred to'),
     }, async (args) => {
         try {
-            const { agent_id, ...input } = args;
-            const result = await functions.createFunction(agent_id, input);
-            return success(result);
+            const { agent_id, type, name, description } = args;
+            const configurationSchema = skillConfiguration(type, withAuthorization(args));
+            // copilot sends a REST answer straight to the customer unless craftResponse is on; with nothing to say
+            // how to present it, let the agent phrase it.
+            if (type === 'rest_api' && configurationSchema && configurationSchema.craftResponse === undefined && !configurationSchema.outputInstructions) {
+                configurationSchema.craftResponse = true;
+            }
+            if (type === 'rest_api' && !(configurationSchema?.endpoint && configurationSchema?.method)) {
+                throw new Error('A rest_api skill needs url and method.');
+            }
+            if (type === 'transfer_call' && !(configurationSchema?.phoneNumber || configurationSchema?.sipUri)) {
+                throw new Error('A transfer_call skill needs transfer_to: a phone number (E.164, e.g. +15551234567) or a SIP address (sip:...).');
+            }
+            // A retry must not leave copies: one skill per name on an agent.
+            const same = name ? (await functions.listFunctions(agent_id)).find((f) => (f.name ?? '').trim().toLowerCase() === name.trim().toLowerCase()) : undefined;
+            if (same)
+                throw new Error(`The agent already has a skill named "${name}" (function_id ${same._id}). Change it with update_function instead of creating another.`);
+            // copilot turns configurationSchema into the executable form only on update: create, then configure.
+            const created = await functions.createFunction(agent_id, { type, name, description });
+            if (!configurationSchema)
+                return success(created);
+            try {
+                return success(await functions.updateFunction(agent_id, created._id, { type, description: description ?? '', configurationSchema }));
+            }
+            catch (err) {
+                // Leave no half-made skill behind: remove the empty one, then say why nothing was saved.
+                const why = err instanceof Error ? err.message : String(err);
+                try {
+                    await functions.deleteFunction(agent_id, created._id);
+                }
+                catch {
+                    throw new Error(`Skill ${created._id} was created, but its configuration was not saved (${why}). Remove it with delete_function, or fix it with update_function.`);
+                }
+                throw new Error(`Nothing was saved: the skill's configuration was refused (${why}). Fix it and call create_function again.`);
+            }
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('update_function', 'Update an existing function (tool) for an agent', {
+    reg.tool('update_function', 'Change a skill of an agent (name, description, configurationSchema).', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID'),
         description: z.string().optional().describe('Updated description'),
         name: z.string().optional().describe('Updated function name'),
-        url: z.string().optional().describe('Updated endpoint URL'),
-        method: z.string().optional().describe('Updated HTTP method'),
+        url: z.string().optional().describe('rest_api: new endpoint URL'),
+        method: z.string().optional().describe('rest_api: new HTTP method'),
+        payload: z.union([z.string(), z.record(z.any())]).optional().describe('rest_api: new request body (JSON) with {{parameter}} placeholders'),
+        response_field: z.string().optional().describe('rest_api: new response dot-path'),
+        output_instructions: z.string().optional().describe('New text the agent says with the answer; {{response.field}} reads the API answer'),
+        craft_response: z.boolean().optional().describe('true: the agent phrases the answer; false: it goes to the customer as is'),
+        ...skillAuthFields,
+        configuration: jsonObject().optional().describe('Other configurationSchema fields to change (an object, or JSON text); the rest of the saved configuration is kept'),
+        transfer_to: z.string().optional().describe('transfer_call: new phone number (E.164) or SIP address; replaces the saved destination'),
     }, async (args) => {
         try {
-            const { agent_id, function_id, ...input } = args;
-            const result = await functions.updateFunction(agent_id, function_id, input);
-            return success(result);
+            const { agent_id } = args;
+            // copilot needs type and description on every update and replaces the configuration whole.
+            const current = await skillOf(agent_id, args.function_id);
+            const function_id = current._id;
+            const input = {
+                type: current.type, description: args.description ?? current.description ?? '',
+            };
+            if (args.name)
+                input.name = args.name;
+            const configurationSchema = skillConfiguration(current.type, withAuthorization(args), current.configurationSchema ?? {});
+            if (configurationSchema)
+                input.configurationSchema = configurationSchema;
+            return success(await functions.updateFunction(agent_id, function_id, input));
         }
         catch (err) {
             return error(err);
         }
-    });
-    server.tool('delete_function', 'Delete a function (tool) from an agent', {
+    }, liveChange('a skill', ['function_id']));
+    reg.tool('delete_function', 'Remove a skill from an agent.', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID to delete'),
     }, async (args) => {
         try {
-            await functions.deleteFunction(args.agent_id, args.function_id);
-            return success({ deleted: true, agent_id: args.agent_id, function_id: args.function_id });
+            const skill = await skillOf(args.agent_id, args.function_id);
+            await functions.deleteFunction(args.agent_id, skill._id);
+            return success({ deleted: true, agent_id: args.agent_id, function_id: skill._id, name: skill.name });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('test_function', 'Test a function (tool) with optional parameters', {
+    reg.tool('test_function', 'Run a skill once with sample parameters and return what its API answered. Calls the real endpoint.', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID to test'),
-        params: z.record(z.unknown()).optional().describe('Test parameters to send'),
+        params: jsonObject().optional().describe('Sample values for the skill\'s {{parameter}} placeholders (an object, or JSON text)'),
     }, async (args) => {
         try {
-            const result = await functions.testFunction(args.agent_id, args.function_id, args.params);
-            return success(result);
+            // copilot's test route runs the configuration it is sent (not the saved one) and sends the body as is:
+            // send the saved configuration with the sample values in place of its placeholders.
+            const current = await skillOf(args.agent_id, args.function_id);
+            const params = (args.params ?? {});
+            const fill = (v) => (typeof v === 'string'
+                ? v.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (m, k) => (k in params ? String(params[k]) : m))
+                : v);
+            const config = Object.fromEntries(Object.entries(current.configurationSchema ?? {}).map(([k, v]) => [k, fill(v)]));
+            return success(await functions.testFunction(args.agent_id, current._id, config));
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('export_functions', 'Export all functions from an agent', { agent_id: z.string().describe('The agent ID') }, async (args) => {
+    reg.tool('export_functions', 'Export every skill of an agent as a JSON file (to copy them or keep a backup before import_functions).', { agent_id: z.string().describe('The agent ID') }, async (args) => {
         try {
             const result = await functions.exportFunctions(args.agent_id);
             return success(result);
@@ -231,7 +646,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('import_functions', 'Import functions into an agent from a URL (e.g. OpenAPI spec)', {
+    reg.tool('import_functions', 'Import functions into an agent from a URL (e.g. OpenAPI spec)', {
         agent_id: z.string().describe('The agent ID'),
         url: z.string().describe('URL to import functions from'),
     }, async (args) => {
@@ -243,36 +658,73 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('list_function_parameters', 'List parameters for a function', {
+    reg.tool('generate_skills_from_doc', 'Propose skills from an API document (file path on this machine) or pasted text. Creates nothing: review the proposal, then call bulk_create_skills.', {
+        agent_id: z.string().describe('The agent ID'),
+        file_path: z.string().optional().describe('Path of a document on this machine'),
+        text: z.string().optional().describe('Text to read instead of a file'),
+    }, async (args) => {
+        try {
+            if (!args.file_path && !args.text)
+                throw new Error('Give file_path or text.');
+            const proposal = await functions.generateFromDoc(args.agent_id, { filePath: args.file_path, text: args.text });
+            return success({ proposed: proposedSkills(proposal), raw: proposedSkills(proposal) ? undefined : proposal });
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('bulk_create_skills', 'Create several skills on an agent at once, for example the proposal from generate_skills_from_doc. Names are checked first; a failure part-way can leave some created.', {
+        agent_id: z.string().describe('The agent ID'),
+        functions: z.array(skillDefinition).min(1).describe('Skill definitions'),
+    }, async (args) => {
+        try {
+            const skills = args.functions.map((f) => {
+                const { url, method, payload, response_field, output_instructions, transfer_to, auth_type, auth_token, auth_key, auth_value, auth_username, auth_password, ...rest } = f;
+                const built = skillConfiguration(String(f.type), withAuthorization({
+                    url: url, method: method, payload, response_field: response_field,
+                    output_instructions: output_instructions, transfer_to: transfer_to,
+                    auth_type, auth_token, auth_key, auth_value, auth_username, auth_password,
+                    configuration: rest.configurationSchema,
+                }));
+                return built ? { ...rest, configurationSchema: built } : rest;
+            });
+            return success(await functions.bulkCreate(args.agent_id, skills));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_function_parameters', 'The parameters a skill collects from the customer before it runs.', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID'),
     }, async (args) => {
         try {
-            const result = await functions.listParameters(args.agent_id, args.function_id);
+            const result = await functions.listParameters(args.agent_id, (await skillOf(args.agent_id, args.function_id))._id);
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('add_function_parameter', 'Add a parameter to a function', {
+    reg.tool('add_function_parameter', 'Add a parameter the skill should collect (name, type, description, required).', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID'),
         name: z.string().describe('Parameter name'),
         type: z.string().describe('Parameter type (string, number, boolean)'),
         description: z.string().optional().describe('Parameter description'),
         required: z.boolean().optional().describe('Whether the parameter is required'),
+        allowed_values: z.array(z.string()).optional().describe('Fixed choices the customer picks from (shown as buttons); omit for free text'),
     }, async (args) => {
         try {
-            const { agent_id, function_id, ...param } = args;
-            const result = await functions.addParameter(agent_id, function_id, param);
+            const { agent_id, function_id, allowed_values, ...param } = args;
+            const result = await functions.addParameter(agent_id, (await skillOf(agent_id, function_id))._id, { ...param, allowedValues: allowed_values });
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('update_function_parameter', 'Update a function parameter', {
+    reg.tool('update_function_parameter', 'Change a skill parameter.', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID'),
         parameter_id: z.string().describe('The parameter ID'),
@@ -280,39 +732,41 @@ export function registerTools(server, client) {
         type: z.string().optional().describe('Updated type'),
         description: z.string().optional().describe('Updated description'),
         required: z.boolean().optional().describe('Updated required flag'),
+        allowed_values: z.array(z.string()).optional().describe('New fixed choices; [] removes them. Anything not given stays as it is'),
     }, async (args) => {
         try {
-            const { agent_id, function_id, parameter_id, ...param } = args;
-            const result = await functions.updateParameter(agent_id, function_id, parameter_id, param);
+            const { agent_id, function_id, parameter_id, allowed_values, ...param } = args;
+            const result = await functions.updateParameter(agent_id, (await skillOf(agent_id, function_id))._id, parameter_id, { ...param, allowedValues: allowed_values });
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('delete_function_parameter', 'Delete a function parameter', {
+    reg.tool('delete_function_parameter', 'Remove a skill parameter.', {
         agent_id: z.string().describe('The agent ID'),
         function_id: z.string().describe('The function ID'),
         parameter_id: z.string().describe('The parameter ID'),
     }, async (args) => {
         try {
-            await functions.deleteParameter(args.agent_id, args.function_id, args.parameter_id);
+            await functions.deleteParameter(args.agent_id, (await skillOf(args.agent_id, args.function_id))._id, args.parameter_id);
             return success({ deleted: true });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('list_master_functions', 'List available master function templates', {}, async () => {
+    reg.tool('list_master_functions', 'Built-in skill types an agent can use as starting points (pass agent_id to get the ones for its channels, e.g. voice).', { agent_id: z.string().optional().describe('Agent whose channels (WEB, VOICE) decide which templates apply') }, async (args) => {
         try {
-            const result = await functions.listMasterFunctions();
+            const channels = args.agent_id ? (await agents.getAgent(args.agent_id)).channels : undefined;
+            const result = await functions.listMasterFunctions(channels?.map((c) => (typeof c === 'string' ? c : String(c.type ?? ''))).filter(Boolean));
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('list_llm_models', 'List available LLM models', {}, async () => {
+    reg.tool('list_llm_models', 'LLM providers and models an agent can run on (use provider/model with set_config).', {}, async () => {
         try {
             const result = await functions.listLLMModels();
             return success(result);
@@ -324,27 +778,27 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Knowledge base tools
     // ---------------------------------------------------------------------------
-    server.tool('list_knowledge_bases', 'List all knowledge bases in the organization', { limit: z.number().optional().describe('Maximum number of KBs to return') }, async (args) => {
+    reg.tool('list_knowledge_bases', 'List the org\'s knowledge bases (what agents can look answers up in), with the agents each is linked to.', {}, async () => {
         try {
-            let result = await kb.listKBs();
-            if (args.limit)
-                result = result.slice(0, args.limit);
-            return success(result);
+            // A website base lists every crawled page (100k characters for a large site); get_knowledge_base has them.
+            const kbs = (await kb.listKBs());
+            const pages = await orgPages(client);
+            return success(kbs.map(({ fileWebSources, kbSampleFaqs: _faqs, ...rest }) => ({ ...rest, sources: fileWebSources?.length ?? 0, url: `${pages}/ai-studio/knowledge-base/${rest._id}` })));
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('get_knowledge_base', 'Get details of a specific knowledge base', { kb_id: z.string().describe('The knowledge base ID') }, async (args) => {
+    reg.tool('get_knowledge_base', 'One knowledge base with its website and file sources and their crawl status.', { kb_id: z.string().describe('The knowledge base ID') }, async (args) => {
         try {
             const result = await kb.getKB(args.kb_id);
-            return success(result);
+            return success({ ...result, url: `${await orgPages(client)}/ai-studio/knowledge-base/${args.kb_id}` });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('create_knowledge_base', 'Create a new knowledge base', {
+    reg.tool('create_knowledge_base', 'Create a knowledge base. type QNA (question/answer pairs), URL (websites) or FILE (documents).', {
         name: z.string().describe('Knowledge base name'),
         type: z.string().describe('Knowledge base type'),
     }, async (args) => {
@@ -356,7 +810,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('update_knowledge_base', 'Update an existing knowledge base', {
+    reg.tool('update_knowledge_base', 'Rename a knowledge base.', {
         kb_id: z.string().describe('The knowledge base ID'),
         name: z.string().optional().describe('Updated name'),
         description: z.string().optional().describe('Updated description'),
@@ -374,7 +828,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('delete_knowledge_base', 'Delete a knowledge base', { kb_id: z.string().describe('The knowledge base ID to delete') }, async (args) => {
+    reg.tool('delete_knowledge_base', 'Delete a knowledge base with all its sources. It must be unlinked from every agent first.', { kb_id: z.string().describe('The knowledge base ID to delete') }, async (args) => {
         try {
             await kb.deleteKB(args.kb_id);
             return success({ deleted: true, kb_id: args.kb_id });
@@ -383,7 +837,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('list_kb_data', 'List data sources in a knowledge base', {
+    reg.tool('list_kb_data', 'The question/answer pairs typed into a knowledge base (website and file sources are listed by get_knowledge_base).', {
         kb_id: z.string().describe('The knowledge base ID'),
         page: z.number().optional().describe('Page number'),
         limit: z.number().optional().describe('Items per page'),
@@ -401,7 +855,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('add_kb_data', 'Add a data source entry to a knowledge base. For URL scraping use scrape_url instead. For file uploads use upload_kb_file.', {
+    reg.tool('add_kb_data', 'Add a data source entry to a knowledge base. For URL scraping use scrape_url instead. For file uploads use upload_kb_file.', {
         kb_id: z.string().describe('The knowledge base ID'),
         question: z.string().optional().describe('FAQ question'),
         answer: z.string().optional().describe('FAQ answer'),
@@ -421,7 +875,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('scrape_url', 'Scrape a website URL and add it as a data source to a knowledge base. Initiates async crawling.', {
+    reg.tool('scrape_url', 'Scrape a website URL and add it as a data source to a knowledge base. Initiates async crawling.', {
         kb_id: z.string().describe('The knowledge base ID'),
         url: z.string().describe('URL to scrape'),
         crawl_mode: z.string().optional().describe('Crawl mode: "full" (entire site) or "selected"'),
@@ -434,7 +888,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('upload_kb_file', 'Upload a file to a knowledge base', {
+    reg.tool('upload_kb_file', 'Upload a document from this machine into a knowledge base; it is read in the background (see kb_scrape_status).', {
         kb_id: z.string().describe('The knowledge base ID'),
         file_path: z.string().describe('Path to the file to upload'),
     }, async (args) => {
@@ -446,7 +900,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('update_kb_data', 'Update a data source entry in a knowledge base', {
+    reg.tool('update_kb_data', 'Change a question/answer pair of a knowledge base.', {
         kb_id: z.string().describe('The knowledge base ID'),
         source_id: z.string().describe('The data source ID'),
         question: z.string().optional().describe('Updated question'),
@@ -463,7 +917,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('delete_kb_data', 'Delete a data source entry from a knowledge base', {
+    reg.tool('delete_kb_data', 'Delete a source of a knowledge base.', {
         kb_id: z.string().describe('The knowledge base ID'),
         source_id: z.string().describe('The data source ID to delete'),
     }, async (args) => {
@@ -475,7 +929,57 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('link_kb', 'Link knowledge bases to an agent', {
+    reg.tool('kb_chunks', 'The text chunks the agent actually retrieves from one knowledge base source. Use it to check what was learned from a page or file.', { kb_id: z.string(), source_id: z.string() }, async (args) => {
+        try {
+            return success(await kb.chunks(args.kb_id, args.source_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('reimport_kb_source', 'Crawl a website source again after the site changed. Runs in the background; follow it with kb_scrape_status.', { kb_id: z.string(), source_id: z.string() }, async (args) => {
+        try {
+            return success(await kb.reimport(args.kb_id, args.source_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('kb_scrape_status', 'Progress of website crawls and file imports of a knowledge base (per source: status, job status, error).', { kb_id: z.string() }, async (args) => {
+        try {
+            return success(await kb.scrapeStatus(args.kb_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('kb_gaps', 'Questions the agents could not answer, to decide what to add to the knowledge base. themes: true groups them by topic.', {
+        agent_id: z.string().optional(),
+        kb_id: z.string().optional(),
+        themes: z.boolean().optional(),
+        days: z.number().int().min(1).max(365).optional().describe('With themes: look back this many days'),
+        include_test: z.boolean().optional(),
+        page: z.number().int().min(0).optional().describe('Starting at 0'),
+        limit: z.number().int().min(1).max(100).optional(),
+    }, async (args) => {
+        try {
+            if (args.themes)
+                return success(await kb.gapClusters({ days: args.days, page: args.page, limit: args.limit }));
+            return success(await kb.gaps({ agentId: args.agent_id, kbId: args.kb_id, includeTest: args.include_test, page: args.page, limit: args.limit }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('kb_check', 'Could the org\'s knowledge bases answer this question? Returns whether it is answerable, the top score and the matching chunks.', { question: z.string() }, async (args) => {
+        try {
+            return success(await kb.check(args.question));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('link_kb', 'Let an agent answer from these knowledge bases.', {
         agent_id: z.string().describe('The agent ID'),
         kb_ids: z.array(z.string()).describe('Array of knowledge base IDs to link'),
     }, async (args) => {
@@ -487,7 +991,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('unlink_kb', 'Unlink a knowledge base from an agent', {
+    reg.tool('unlink_kb', 'Stop an agent from using a knowledge base.', {
         agent_id: z.string().describe('The agent ID'),
         kb_id: z.string().describe('The knowledge base ID to unlink'),
     }, async (args) => {
@@ -499,7 +1003,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('export_kb', 'Export knowledge base data', {
+    reg.tool('export_kb', 'Export the question/answer pairs of a knowledge base as a CSV or XLSX download link.', {
         kb_id: z.string().describe('The knowledge base ID'),
         format: z.string().optional().describe('Export format (e.g. "json", "csv")'),
     }, async (args) => {
@@ -511,7 +1015,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('import_kb', 'Import data into a knowledge base', {
+    reg.tool('import_kb', 'Import websites or files into a knowledge base; processed in the background (see kb_scrape_status).', {
         kb_id: z.string().describe('The knowledge base ID'),
         data: z.record(z.unknown()).describe('Data to import'),
     }, async (args) => {
@@ -526,125 +1030,855 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Chat tool
     // ---------------------------------------------------------------------------
-    server.tool('chat_with_agent', 'Send a message to an agent and get a response. Not interactive — sends one message and returns the reply.', {
-        agent_id: z.string().describe('The agent ID (bot type) to chat with'),
-        message: z.string().describe('The message to send'),
-        session_id: z.string().optional().describe('Optional session ID to continue a conversation'),
-    }, async (args) => {
-        try {
-            const middlewareUrl = client.getHosts().middleware;
-            const chat = new ChatSession(args.agent_id, middlewareUrl, args.session_id);
-            // Track streaming state to distinguish greeting from response
-            let receiving = false;
-            let messageCount = 0;
-            chat.on('stream', (data) => {
-                if (data.isFirstChunk)
-                    receiving = true;
-                if (data.streamFinished)
-                    receiving = false;
-            });
-            const greetingMessages = [];
-            chat.on('message', (text) => {
-                greetingMessages.push(text);
-                messageCount++;
-            });
-            const sessionId = await chat.connect();
-            // Wait for greeting to finish streaming (up to 8s)
-            await new Promise((resolve) => {
-                const check = setInterval(() => {
-                    if (!receiving) {
-                        clearInterval(check);
-                        resolve();
-                    }
-                }, 100);
-                setTimeout(() => { clearInterval(check); resolve(); }, 8000);
+    const conversations = new ConversationsSDK(client);
+    reg.tool('list_conversations', 'List conversations of one agent in the org, newest first, including test ones, with whether each is a test and whether the CLI opened it.', {
+        agent_id: z.string().describe('Agent whose conversations to list'),
+        limit: z.number().int().min(1).max(100).optional().describe('Rows per page (default 50, at most 100)'),
+        page: z.number().int().min(0).optional().describe('Page, starting at 0'),
+        live_only: z.boolean().optional().describe('Hide test conversations'),
+        cli_only: z.boolean().optional().describe('Only conversations opened by the CLI'),
+    }, async (args) => {
+        try {
+            const res = await conversations.list(args.agent_id, {
+                limit: args.limit, page: args.page, includeTest: !args.live_only, cliOnly: args.cli_only,
             });
-            // Now swap the listener — next message is the actual response
-            const greetingCount = messageCount;
-            chat.removeAllListeners('message');
-            const response = await new Promise((resolve, reject) => {
-                const timeout = setTimeout(() => {
-                    chat.disconnect();
-                    reject(new Error('Agent did not respond within 60 seconds'));
-                }, 60000);
-                chat.on('message', (text) => {
-                    clearTimeout(timeout);
-                    resolve(text);
-                });
-                chat.send(args.message);
+            return success(res.conversations.map((c) => ({
+                conversation_id: c.request_id, created_at: c.created_at ?? c.createdAt, test: isTestConversation(c),
+                cli: isCliConversation(c), first_message: c.first_text,
+            })));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_conversation', 'Get one conversation and its messages (who said what, oldest first). format "testset" returns it as an evaluation test set with one scenario item to replay.', {
+        agent_id: z.string().describe('Agent the conversation belongs to'),
+        conversation_id: z.string().describe('Conversation (request) id'),
+        format: z.enum(['messages', 'testset']).optional().describe('messages (default) or testset'),
+    }, async (args) => {
+        try {
+            const projectId = await projectOfAgent(client, args.agent_id);
+            const [conversation, messages] = await Promise.all([
+                conversations.get(projectId, args.conversation_id),
+                conversations.messages(projectId, args.conversation_id, args.agent_id),
+            ]);
+            if (args.format === 'testset')
+                return success(conversationToTestSet(conversation, messages, args.agent_id));
+            return success({
+                conversation_id: conversation.request_id, test: conversation.isTestMode === true,
+                url: conversationUrl(client, projectId, conversation.request_id),
+                messages: messages.map((m) => ({ role: m.role, text: m.text, at: m.createdAt })),
             });
-            chat.disconnect();
-            return success({ session_id: sessionId, greeting: greetingMessages.slice(0, greetingCount).join('\n'), response });
         }
         catch (err) {
             return error(err);
         }
     });
-    // ---------------------------------------------------------------------------
-    // Eval tools
-    // ---------------------------------------------------------------------------
-    server.tool('run_evaluation', 'Trigger an evaluation run for a bot against a test set', {
-        bot_id: z.string().describe('The bot ID to evaluate'),
-        test_set_id: z.string().describe('The test set ID'),
-        rubric_id: z.string().optional().describe('Optional rubric ID'),
-        concurrency: z.number().optional().describe('Number of concurrent evaluations'),
-        eval_model: z.string().optional().describe('Model to use for evaluation judging'),
-        keep: z.boolean().optional().describe('Keep evaluation data after completion'),
-        limit: z.number().optional().describe('Limit items to evaluate'),
-        component_scope: z.string().optional().describe('Component scope filter'),
-        component_ids: z.array(z.string()).optional().describe('Component ID filter'),
-        mode: z.string().optional().describe('Evaluation mode'),
+    reg.tool('mark_conversation_test', 'Mark conversations as test, as the dashboard does: removed from analytics and usage billing reversed.', {
+        agent_id: z.string().describe('Agent the conversations belong to'),
+        conversation_ids: z.array(z.string()).min(1).max(100).describe('Conversation (request) ids'),
     }, async (args) => {
         try {
-            const input = {
-                bot_id: args.bot_id,
-                test_set_id: args.test_set_id,
-            };
-            if (args.rubric_id !== undefined)
-                input.rubric_id = args.rubric_id;
-            if (args.concurrency !== undefined)
-                input.concurrency = args.concurrency;
-            if (args.eval_model !== undefined)
-                input.eval_model = args.eval_model;
-            if (args.keep !== undefined)
-                input.keep = args.keep;
-            if (args.limit !== undefined)
-                input.limit = args.limit;
-            if (args.component_scope !== undefined)
-                input.component_scope = args.component_scope;
-            if (args.component_ids !== undefined)
-                input.component_ids = args.component_ids;
-            if (args.mode !== undefined)
-                input.mode = args.mode;
-            const result = await evals.triggerEvaluation(input);
-            return success(result);
+            const projectId = await projectOfAgent(client, args.agent_id);
+            const done = [];
+            for (const id of args.conversation_ids) {
+                await conversations.markTest(projectId, id);
+                done.push(id);
+            }
+            return success({ marked_test: done });
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('get_eval_status', 'Get the status of an evaluation run', { run_id: z.string().describe('The evaluation run ID') }, async (args) => {
+    const voice = new VoiceSDK(client);
+    reg.tool('list_voices', 'Text-to-speech voices of a provider (cartesia default, or elevenlabs), filterable by language, gender and name.', {
+        provider: z.enum(['cartesia', 'elevenlabs']).optional(),
+        language: z.string().optional(),
+        gender: z.enum(['masculine', 'feminine', 'gender_neutral']).optional(),
+        search: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    }, async (args) => {
         try {
-            const result = await evals.getRunStatus(args.run_id);
-            return success(result);
+            return success(await voice.listVoices({ provider: args.provider, language: args.language, gender: args.gender, q: args.search, limit: args.limit }));
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('get_eval_results', 'Get the detailed results of a completed evaluation run', { run_id: z.string().describe('The evaluation run ID') }, async (args) => {
+    reg.tool('list_voice_models', 'Speech provider and model catalog: stt (speech to text) or tts (text to speech).', { kind: z.enum(['stt', 'tts']) }, async (args) => {
         try {
-            const result = await evals.getRunResults(args.run_id);
-            return success(result);
+            return success(await voice.voiceModels(args.kind));
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('get_bot_context', 'Get the full context of a bot (prompt, tools, KBs, LLM config)', { bot_id: z.string().describe('The bot ID') }, async (args) => {
+    reg.tool('get_agent_voice', 'Voice settings of an agent (text-to-speech voice, speech-to-text, noise cancellation, interruption). They live on its phone number; an agent without one has none.', { agent_id: z.string() }, async (args) => {
         try {
-            const result = await evals.getBotContext(args.bot_id);
-            return success(result);
+            return success(await voice.getAgentVoice(args.agent_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_agent_voice', 'Change the text-to-speech voice of an agent. Take voice_id, name, gender, language and country_code from list_voices.', {
+        agent_id: z.string(),
+        provider: z.enum(['cartesia', 'elevenlabs']).optional(),
+        voice_id: z.string(),
+        name: z.string(),
+        gender: z.string(),
+        language: z.string(),
+        country_code: z.string(),
+        model: z.string().optional(),
+        speed: z.number().optional(),
+    }, async (args) => {
+        try {
+            return success(await voice.setAgentVoice(args.agent_id, {
+                provider: args.provider ?? 'cartesia', voice_id: args.voice_id, name: args.name, gender: args.gender, language: args.language,
+                countryCode: args.country_code, ...(args.model ? { model: args.model } : {}), ...(args.speed ? { settings: { speed: args.speed } } : {}),
+            }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_agent_transcriber', 'Change how a voice agent hears callers (speech-to-text): provider and model from list_voice_models (kind stt), language, and key terms to listen for (names, products).', {
+        agent_id: z.string(),
+        provider: z.string(),
+        model: z.string(),
+        language: z.string(),
+        keyterms: z.array(z.string()).optional().describe('Up to 50 words or phrases, 100 characters each'),
+    }, async (args) => {
+        try {
+            return success(await voice.setAgentTranscriber(args.agent_id, { provider: args.provider, model: args.model, language: args.language, keyterms: args.keyterms }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_agent_numbers', 'Phone numbers attached to an agent, or (without agent_id) every number the org owns.', { agent_id: z.string().optional() }, async (args) => {
+        try {
+            return success(args.agent_id ? await voice.agentNumbers(args.agent_id) : await voice.orgNumbers());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('attach_phone_number', 'Attach a phone number the org already owns to an agent. Never buys a number.', { agent_id: z.string(), phone_number: z.string() }, async (args) => {
+        try {
+            return success(await voice.attachNumber(args.agent_id, args.phone_number));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('search_phone_numbers', 'Numbers available to buy for a voice agent (US, CA, GB, AU; local or toll-free). Free: nothing is bought. First ask the person what kind of number they want (local with which area code, or toll-free), then search and show 4-5 numbers with their location, and buy only the one they choose.', {
+        area_code: z.string().optional().describe('Three-digit area code, e.g. 331'),
+        contains: z.string().optional().describe('Digits the number should contain'),
+        country: z.enum(['US', 'CA', 'GB', 'AU']).optional().describe('Default US'),
+        toll_free: z.boolean().optional(),
+        limit: z.number().int().min(1).max(20).optional().describe('How many (default 5)'),
+    }, async (args) => {
+        try {
+            return success(await voice.searchNumbers({ areaCode: args.area_code, contains: args.contains, country: args.country, tollFree: args.toll_free, limit: args.limit }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_phone_number', 'The phone number of a voice agent: number, location, type, and a summary of its voice and transcriber.', { agent_id: z.string() }, async (args) => {
+        try {
+            return success(await voice.numberDetails(args.agent_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('buy_phone_number', 'Buy a number from search_phone_numbers and attach it to a voice agent (costs the org money every month; no undo here). Only after the person chose that exact number. The host asks the person to approve; without an approval form this is refused.', {
+        agent_id: z.string(),
+        phone_number: z.string().describe('The number the person chose, as search_phone_numbers returned it'),
+        country: z.enum(['US', 'CA', 'GB', 'AU']).optional(),
+        toll_free: z.boolean().optional(),
+    }, async (args, meta) => {
+        try {
+            // A purchase needs the person, not the model: confirm: true from a host without approval forms is not enough.
+            if (!meta.confirmedByPerson)
+                throw new Error('Buying a number needs a person to approve it in an approval form, and this host cannot show one. Nothing was bought. Buy it in the dashboard, or with `indemn agents numbers buy` in a terminal.');
+            return success(await voice.buyNumber(args.agent_id, args.phone_number, { country: args.country, tollFree: args.toll_free }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('detach_phone_number', 'Detach a phone number from an agent; the org keeps owning it.', { agent_id: z.string(), phone_number: z.string() }, async (args) => {
+        try {
+            return success(await voice.detachNumber(args.agent_id, args.phone_number));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('voice_preview', 'A browser link for a test voice call with an agent (marked as test, valid 1 hour). Give the join_url to the user; do not share it further.', { agent_id: z.string() }, async (args) => {
+        try {
+            return success(await voice.voicePreview(args.agent_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    const distribution = new DistributionSDK(client);
+    reg.tool('list_distributions', 'Website paths that open agents (web widget) and the org\'s embed code.', {}, async () => {
+        try {
+            return success(await distribution.list());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_embed_code', 'The embed code and the website paths that open one agent.', { agent_id: z.string() }, async (args) => {
+        try {
+            return success(await distribution.embed(args.agent_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('create_distribution', 'Open an agent on a website path. Visitors of that page see it once the embed code is on the site.', { agent_id: z.string(), host: z.string(), path: z.string(), path_expression: z.string().optional(), greeting: z.string().optional(), allow_upload: z.boolean().optional() }, async (args) => {
+        try {
+            return success(await distribution.create({ agentId: args.agent_id, host: args.host, path: args.path, pathExpression: args.path_expression, greeting: args.greeting, allowUpload: args.allow_upload }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('update_distribution', 'Change a website distribution of this org: which agent it opens, its greeting or page pattern.', { distribution_id: z.string(), agent_id: z.string().optional(), greeting: z.string().optional(), path_expression: z.string().optional() }, async (args) => {
+        try {
+            const changes = {};
+            if (args.agent_id)
+                changes.id_bot = args.agent_id;
+            if (args.greeting)
+                changes.greetingMessage = args.greeting;
+            if (args.path_expression)
+                changes.pathExpression = args.path_expression;
+            return success(await distribution.update(args.distribution_id, changes));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_templates', 'Agent templates, shared by every org on the platform.', {}, async () => {
+        try {
+            return success(await distribution.listTemplates());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('create_template', 'Publish an agent of this org as a template that every org can copy.', { agent_id: z.string(), name: z.string(), description: z.string().optional(), category: z.array(z.string()).optional(), tags: z.array(z.string()).optional() }, async (args) => {
+        try {
+            return success(await distribution.createTemplate({ agentId: args.agent_id, name: args.name, description: args.description, category: args.category, tags: args.tags }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('delete_template', 'Remove a template made from an agent of this org.', { template_id: z.string() }, async (args) => {
+        try {
+            return success(await distribution.deleteTemplate(args.template_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('create_agent_from_template', 'Create a new agent in this org copied from a template (prompt, model, skills, knowledge bases; not phone numbers, voice settings or distributions).', { template_id: z.string(), name: z.string().describe('Name of the new agent'), channels: z.array(z.string()).optional() }, async (args) => {
+        try {
+            if ((await agents.findByName(args.name)).length)
+                throw new Error(`An agent named "${args.name}" already exists in this org.`);
+            return success(await distribution.createFromTemplate(args.template_id, { name: args.name, channels: args.channels }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_solutions', 'Solutions of the org with their connected systems.', {}, async () => {
+        try {
+            return success(await distribution.listSolutions());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    const analytics = new AnalyticsSDK(client);
+    const orgSettings = new OrgSettingsSDK(client);
+    const range = {
+        date_from: z.string().optional().describe('YYYY-MM-DD, default 30 days ago'),
+        date_to: z.string().optional().describe('YYYY-MM-DD, default today'),
+        channel: z.enum(['web', 'voice', 'all']).optional(),
+        agent_id: z.string().optional().describe('Only this agent'),
+    };
+    reg.tool('get_analytics', 'Dashboard analytics (test conversations excluded): metrics, model-performance, model-performance/bots, agent-volume, handoff-precursors, critical-feedback.', { kind: z.enum(['metrics', 'model-performance', 'model-performance/bots', 'agent-volume', 'handoff-precursors', 'critical-feedback']), ...range }, async (args) => {
+        try {
+            return success(await analytics.get(args.kind, { from: args.date_from, to: args.date_to, channel: args.channel, agentId: args.agent_id }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_analytics_conversations', 'The conversations behind an analytics number, filtered by a dimension (outcome, feedback, sentiment, precursor, reason, critical_feedback_theme, attribute:<key>).', { ...range, dimension: z.string().optional(), value: z.string().optional(), search: z.string().optional(), page: z.number().int().min(1).optional(), page_size: z.number().int().min(1).max(200).optional() }, async (args) => {
+        try {
+            return success(await analytics.conversations({ from: args.date_from, to: args.date_to, channel: args.channel, agentId: args.agent_id, dimension: args.dimension, value: args.value, search: args.search, page: args.page, pageSize: args.page_size }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_custom_charts', 'Custom charts configured for the org.', {}, async () => {
+        try {
+            return success(await analytics.charts());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_custom_chart', 'Data of one custom chart.', { chart_id: z.string(), ...range }, async (args) => {
+        try {
+            return success(await analytics.chart(args.chart_id, { from: args.date_from, to: args.date_to, channel: args.channel, agentId: args.agent_id }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_org_settings', 'Org settings: timezone, business hours, holidays, handoff settings (read-only) and feature switches.', {}, async () => {
+        try {
+            return success(await orgSettings.get());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_org_timezone', 'Set the org timezone (business hours are read in it).', { timezone: z.string().describe('For example America/New_York') }, async (args) => {
+        try {
+            return success(await orgSettings.setTimezone(args.timezone));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_business_hours', 'Replace the org business hours. days: 0 Sunday to 6; an empty slots list closes that day.', { enabled: z.boolean(), hours: z.array(z.object({ day: z.number().int().min(0).max(6), slots: z.array(z.object({ start: z.string().describe('HH:MM'), end: z.string().describe('HH:MM') })) })).optional(), out_of_hours_message: z.string().optional() }, async (args) => {
+        try {
+            return success(await orgSettings.setBusinessHours({ businessHoursEnabled: args.enabled, businessHours: args.hours, ...(args.out_of_hours_message ? { businessHoursUtterance: args.out_of_hours_message } : {}) }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('add_holiday', 'Close the org on a date.', { date: z.string().describe('YYYY-MM-DD'), name: z.string(), message: z.string().optional().describe('What agents say that day') }, async (args) => {
+        try {
+            return success(await orgSettings.addHolidays([{ name: args.name, date: args.date, ...(args.message ? { holidayFallbackUtterance: args.message } : {}) }]));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('set_org_admin_settings', 'Indemn staff only: the org Settings → Admin tab (feature switches, Intake Manager name, web AI disclosure, conversation timers). Give only what should change; get_org_settings shows the current values.', {
+        conversation_summaries: z.boolean().optional().describe('AI Conversation Summaries: an AI summary when a conversation is closed'),
+        canned_responses: z.boolean().optional().describe('Canned Responses: saved replies agents can insert'),
+        indemn_branding: z.boolean().optional().describe('Show Indemn Branding: the Indemn logo in the chat widget'),
+        underwriting_portal: z.boolean().optional().describe('Underwriting Portal: the Intake Manager item in the sidebar'),
+        underwriting_portal_name: z.string().optional().describe('Name of the Intake Manager item in the sidebar (the default is "Intake Manager")'),
+        smart_inbox: z.boolean().optional().describe('Smart Inbox: email triage and intake'),
+        solutions: z.boolean().optional().describe('Solutions: renewal desks, campaigns and book management'),
+        tickets: z.boolean().optional().describe('Tickets: the tickets page and the ticket scan when a conversation is resolved'),
+        agent_testing: z.boolean().optional().describe('Agent Testing Mode: internal agent testing tools and debug details'),
+        composer_dictation: z.boolean().optional().describe('Composer Dictation: a mic button in the agents\' chat box'),
+        web_ai_disclosure: z.boolean().optional().describe('Show Web AI Disclosure below the first AI reply in the web widget (needs its text)'),
+        web_ai_disclosure_text: z.string().optional().describe('The web AI disclosure text'),
+        ongoing_to_ended_minutes: z.number().int().min(0).optional().describe('Ongoing → Ended: minutes a quiet AI conversation waits before it ends (at least 1; 0 = the default, 30 minutes)'),
+        ended_to_resolved_minutes: z.number().int().min(0).optional().describe('Ended → Resolved: minutes before an ended conversation resolves (at least 10; 0 = the default, 24 hours)'),
+        resolved_to_archived_minutes: z.number().int().min(0).optional().describe('Resolved → Archived: minutes before a resolved conversation is archived (at least 1; 0 = the default, 7 days)'),
+    }, async (args) => {
+        try {
+            const { body } = await orgSettings.planAdmin(args);
+            const saved = (await orgSettings.setAdminSettings(body));
+            return success({ saved: Object.fromEntries(Object.keys(body).map((k) => [k, saved?.orgConfigs?.[k] ?? body[k]])) });
+        }
+        catch (err) {
+            return error(err);
+        }
+    }, { preview: async (a) => `This will ${(await orgSettings.planAdmin(a)).changes.join('; ')}.` });
+    reg.tool('list_audit_logs', 'Who changed what in the org, newest first, filtered here (the server has no filters).', { since: z.string().optional(), action: z.string().optional(), resource_type: z.string().optional(), user_id: z.string().optional(), limit: z.number().int().min(1).max(500).optional() }, async (args) => {
+        try {
+            return success(await new AuditSDK(client).list({ since: args.since, action: args.action, resourceType: args.resource_type, user: args.user_id, limit: args.limit }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    const tickets = new TicketsSDK(client);
+    const ticketStatus = z.enum(['not_started', 'in_progress', 'completed']);
+    const ticketPriority = z.enum(['urgent', 'high', 'normal', 'low']);
+    reg.tool('list_tickets', 'Support tickets of the org, newest first (the org must have tickets turned on).', { status: z.array(ticketStatus).optional(), assignee_user_id: z.string().optional(), search: z.string().optional(), limit: z.number().int().min(1).max(500).optional() }, async (args) => {
+        try {
+            return success(await tickets.list({ status: args.status, assignee: args.assignee_user_id, search: args.search, limit: args.limit }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_ticket', 'One ticket with its conversations and related tickets.', { ticket_id: z.string() }, async (args) => {
+        try {
+            return success(await tickets.get(args.ticket_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('create_ticket', 'Create a ticket. Without force, similar open tickets are looked for first and nothing is created when some exist (the result lists them).', {
+        title: z.string(), description: z.string().optional(), priority: ticketPriority.optional(),
+        assignee_user_id: z.string().optional(), conversation_id: z.string().optional().describe('Conversation (request) id to attach'),
+        force: z.boolean().optional(),
+    }, async (args) => {
+        try {
+            return success(await tickets.create({
+                title: args.title, description: args.description, priority: args.priority,
+                ...(args.assignee_user_id ? { assignee: { type: 'user', target: args.assignee_user_id } } : {}),
+                ...(args.conversation_id ? { conversations: [{ request_id: args.conversation_id }] } : {}),
+            }, { force: args.force }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('update_ticket', 'Change a ticket: fields, assignee (user id, or unassign: true), or close it with resolve: true (and an optional note).', {
+        ticket_id: z.string(), title: z.string().optional(), description: z.string().optional(), notes: z.string().optional(),
+        status: z.enum(['not_started', 'in_progress']).optional(), priority: ticketPriority.optional(),
+        assignee_user_id: z.string().optional(), unassign: z.boolean().optional(), resolve: z.boolean().optional(), note: z.string().optional(),
+        link_ticket_id: z.string().optional().describe('Link to another ticket'),
+    }, async (args) => {
+        try {
+            const out = {};
+            const changes = {};
+            for (const k of ['title', 'description', 'notes', 'status', 'priority'])
+                if (args[k] !== undefined)
+                    changes[k] = args[k];
+            if (Object.keys(changes).length)
+                out.updated = await tickets.update(args.ticket_id, changes);
+            if (args.assignee_user_id || args.unassign)
+                out.assigned = await tickets.assign(args.ticket_id, args.unassign ? null : { type: 'user', target: args.assignee_user_id });
+            if (args.link_ticket_id)
+                out.linked = await tickets.link(args.ticket_id, args.link_ticket_id);
+            if (args.resolve)
+                out.resolved = await tickets.resolve(args.ticket_id, args.note);
+            if (!Object.keys(out).length)
+                throw new Error('Nothing to change.');
+            return success(out);
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('archive_ticket', 'Archive a ticket.', { ticket_id: z.string() }, async (args) => {
+        try {
+            return success(await tickets.archive(args.ticket_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_ticket_rules', 'Rules that let agents open tickets from conversations.', { agent_id: z.string().optional().describe('Only rules enabled for this agent') }, async (args) => {
+        try {
+            return success(await tickets.listRules({ agentId: args.agent_id }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('save_ticket_rule', 'Create a ticket rule (prompt required; checked for overlaps unless force) or change one (rule_id).', {
+        rule_id: z.string().optional(), name: z.string().max(75).optional(), prompt: z.string().optional(),
+        agent_ids: z.array(z.string()).optional().describe('Only these agents; default all'),
+        assignee_user_id: z.string().optional(), enabled: z.boolean().optional(), force: z.boolean().optional(),
+    }, async (args) => {
+        try {
+            return success(await tickets.saveRule({
+                ruleId: args.rule_id, name: args.name, prompt: args.prompt, enabled: args.enabled,
+                ...(args.agent_ids ? { scope: { kind: 'specific', agents: args.agent_ids } } : args.rule_id ? {} : { scope: { kind: 'all_agents', agents: [] } }),
+                ...(args.assignee_user_id ? { assignment: { type: 'user', target: args.assignee_user_id } } : {}),
+            }, { force: args.force }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('delete_ticket_rule', 'Delete a ticket rule.', { rule_id: z.string() }, async (args) => {
+        try {
+            return success(await tickets.deleteRule(args.rule_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_billing', 'Read-only billing: status (subscription), invoices, unpaid (open invoices), usage_forecast, or plans. Nothing here changes a plan or moves money.', { what: z.enum(['status', 'invoices', 'unpaid', 'usage_forecast', 'plans']) }, async (args) => {
+        try {
+            const billing = new BillingSDK(client);
+            const result = args.what === 'status' ? await billing.status()
+                : args.what === 'invoices' ? await billing.invoices()
+                    : args.what === 'unpaid' ? await billing.unpaid()
+                        : args.what === 'usage_forecast' ? await billing.usageForecast()
+                            : await billing.plans();
+            return success(result);
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_campaigns', 'Read-only campaigns: list, one campaign (campaign_id), its counts / forecast / next-touchpoints / versions, templates, one template (template_id, versions: true for subject and body), or template skills.', {
+        what: z.enum(['list', 'campaign', 'counts', 'forecast', 'next-touchpoints', 'versions', 'templates', 'template', 'template-skills']),
+        campaign_id: z.string().optional(), template_id: z.string().optional(), versions: z.boolean().optional(),
+        status: z.string().optional(), solution_id: z.string().optional(), channel: z.string().optional(),
+        days: z.number().int().min(1).max(365).optional(), limit: z.number().int().min(1).max(500).optional(),
+    }, async (args) => {
+        try {
+            const c = new CampaignsSDK(client);
+            const need = (v, name) => { if (!v)
+                throw new Error(`${name} is required for ${args.what}.`); return v; };
+            switch (args.what) {
+                case 'list': return success(await c.list({ status: args.status, solutionId: args.solution_id, limit: args.limit }));
+                case 'campaign': return success(await c.get(need(args.campaign_id, 'campaign_id')));
+                case 'templates': return success(await c.templates({ channel: args.channel, solutionId: args.solution_id, limit: args.limit }));
+                case 'template': return success(await c.template(need(args.template_id, 'template_id'), Boolean(args.versions)));
+                case 'template-skills': return success(await c.templateSkills(args.solution_id));
+                default: return success(await c.detail(need(args.campaign_id, 'campaign_id'), args.what, args.days));
+            }
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    const platform = new PlatformSDK(client);
+    const platformResource = z.enum(['agents', 'templates', 'components', 'connectors', 'connector-bindings', 'scenarios']);
+    reg.tool('platform_list', 'List V2 platform items: agents, templates, components, connectors (shared catalogs), connector-bindings, scenarios (agent_id filters scenarios).', { resource: platformResource, agent_id: z.string().optional() }, async (args) => {
+        try {
+            return success(await platform.list(args.resource, args.agent_id ? { agent_id: args.agent_id } : undefined));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('platform_get', 'One V2 platform item by id.', { resource: platformResource, id: z.string() }, async (args) => {
+        try {
+            return success(await platform.get(args.resource, args.id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('platform_save', 'Create (no id) or change (id) a V2 agent, template, connector binding or scenario. Components and connectors are read-only shared catalogs.', { resource: z.enum(['agents', 'templates', 'connector-bindings', 'scenarios']), id: z.string().optional(), body: z.record(z.unknown()) }, async (args) => {
+        try {
+            return success(args.id ? await platform.update(args.resource, args.id, args.body) : await platform.create(args.resource, args.body));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('platform_delete', 'Delete a V2 agent, template, connector binding or scenario.', { resource: z.enum(['agents', 'templates', 'connector-bindings', 'scenarios']), id: z.string() }, async (args) => {
+        try {
+            return success(await platform.remove(args.resource, args.id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('validate_platform_template', 'Check a V2 template graph: components exist, edges point at real nodes.', { template_id: z.string() }, async (args) => {
+        try {
+            return success(await platform.validateTemplate(args.template_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('run_simulation', 'Run scenarios against a V2 agent; poll simulation_status with the job id.', { agent_id: z.string(), scenario_ids: z.array(z.string()).optional() }, async (args) => {
+        try {
+            return success(await platform.runSimulation(args.agent_id, args.scenario_ids));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('simulation_status', 'Simulation jobs (job_id for one) or results (result_id for one, or the latest of an agent).', { job_id: z.string().optional(), result_id: z.string().optional(), agent_id: z.string().optional() }, async (args) => {
+        try {
+            if (args.job_id)
+                return success(await platform.simulationJob(args.job_id));
+            if (args.result_id)
+                return success(await platform.simulationResults({ resultId: args.result_id }));
+            return success({ jobs: await platform.simulationJobs({ agentId: args.agent_id }), results: await platform.simulationResults({ agentId: args.agent_id }) });
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('org_evaluations', 'Which agents of the org have a baseline evaluation (rubric and test set), and which are stale.', {}, async () => {
+        try {
+            return success(await platform.orgEvaluations());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('jarvis_create_job', 'Ask Jarvis to generate baseline evaluations for 1 to 50 agents of the org. Poll jarvis_jobs with the job id; per-agent failures are in progress.results.', { bot_ids: z.array(z.string()).min(1).max(50) }, async (args) => {
+        try {
+            return success(await platform.createJarvisJob(args.bot_ids));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('jarvis_jobs', 'Jarvis jobs of the org, or one job (job_id).', { job_id: z.string().optional(), status: z.enum(['pending', 'running', 'completed', 'failed']).optional() }, async (args) => {
+        try {
+            return success(args.job_id ? await platform.jarvisJob(args.job_id) : await platform.jarvisJobs(args.status));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('jarvis_chat', 'One turn with Jarvis, the V2 platform assistant. Returns its reply, the tools it used, and a conversation_id to continue. agent_id tells Jarvis which V1 agent this is about.', { message: z.string(), conversation_id: z.string().optional(), agent_id: z.string().optional() }, async (args) => {
+        try {
+            return success(await jarvisChat(client, args.message, { conversationId: args.conversation_id, context: args.agent_id ? { federation_bot_id: args.agent_id } : undefined }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('chat_with_agent', 'Send one message to an agent and return its reply. Always a test conversation: never billed, never in analytics, shown with your name as tester. Pass the returned session_id to continue the same conversation.', {
+        agent_id: z.string().describe('The agent ID to chat with'),
+        message: z.string().describe('The message to send'),
+        session_id: z.string().optional().describe('session_id from an earlier call, to continue that conversation'),
+        end_conversation: z.boolean().optional().describe('End the conversation after this reply (default: keep it open so session_id can continue it)'),
+    }, async (args) => {
+        try {
+            const chat = await openTestChat(client, args.agent_id, { sessionId: args.session_id });
+            try {
+                const { greeting, response } = await exchange(chat, args.message);
+                return success({
+                    session_id: chat.sessionId,
+                    test_conversation: true,
+                    tester: chat.tester,
+                    url: chat.url,
+                    greeting: chat.resumed ? undefined : greeting,
+                    response,
+                });
+            }
+            finally {
+                await chat.session.disconnect({ end: args.end_conversation === true });
+            }
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Eval tools
+    // ---------------------------------------------------------------------------
+    const testSetsForRun = new TestSetsSDK(client);
+    reg.tool('run_evaluation', 'Start an evaluation of an agent against its test set (paid model calls, cannot be cancelled; asks first). The agent must be in the org and the test set must belong to it. date_from/date_to grade real conversations (transcript mode). Poll get_eval_status; eval_gate_verdict judges a finished run.', {
+        agent_id: z.string().optional().describe('The agent ID to evaluate'),
+        bot_id: z.string().optional().describe('Same as agent_id (older name)'),
+        test_set_id: z.string().describe('The test set ID (must belong to this agent)'),
+        rubric_id: z.string().optional().describe('Optional rubric ID'),
+        concurrency: z.number().int().min(1).max(10).optional().describe('Parallel cases (default 1)'),
+        eval_model: z.string().optional().describe('Judge model'),
+        limit: z.number().int().min(1).optional().describe('Only the first N items'),
+        component_scope: z.string().optional(),
+        component_ids: z.array(z.string()).optional(),
+        conversation_ids: z.array(z.string()).optional().describe('Transcript mode: these conversations'),
+        date_from: z.string().optional().describe('Transcript mode: conversations from this ISO date'),
+        date_to: z.string().optional().describe('Transcript mode: up to this ISO date, exclusive'),
+        mode: z.enum(['transcript']).optional(),
+        allow_other_agent: z.boolean().optional().describe('Run a test set written for another agent'),
+    }, async (args) => {
+        try {
+            const agentId = args.agent_id ?? args.bot_id;
+            if (!agentId)
+                throw new Error('Give agent_id: the agent to evaluate.');
+            await evals.assertAgentInOrg(agentId);
+            const ts = await testSetsForRun.getTestSet(args.test_set_id);
+            if (ts.agent_id && ts.agent_id !== agentId && !args.allow_other_agent) {
+                throw new Error(`Test set ${args.test_set_id} was written for agent ${ts.agent_id}, not ${agentId}. Pass allow_other_agent: true to run it anyway.`);
+            }
+            if (Boolean(args.date_from) !== Boolean(args.date_to))
+                throw new Error('date_from and date_to go together.');
+            const input = { bot_id: agentId, test_set_id: args.test_set_id };
+            if (args.rubric_id)
+                input.rubric_id = args.rubric_id;
+            if (args.concurrency)
+                input.concurrency = args.concurrency;
+            // Voice simulations share call rooms; the dashboard runs them one at a time.
+            if ((ts.items ?? []).some((i) => i.type === 'voice_simulation'))
+                input.concurrency = 1;
+            if (args.eval_model)
+                input.eval_model = args.eval_model;
+            if (args.limit)
+                input.limit = args.limit;
+            if (args.component_scope)
+                input.component_scope = args.component_scope;
+            if (args.component_ids)
+                input.component_ids = args.component_ids;
+            if (args.conversation_ids)
+                input.conversation_ids = args.conversation_ids;
+            if (args.mode)
+                input.mode = args.mode;
+            if (args.date_from) {
+                input.date_from = args.date_from;
+                input.date_to = args.date_to;
+                input.mode = 'transcript';
+            }
+            return success(await evals.triggerEvaluation(input));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_eval_status', 'Status and counts of an evaluation run (passed, failed, infrastructure errors, latency). While the run is still going it waits up to wait_seconds for it to finish, so call it again only if it is still running.', {
+        run_id: z.string().describe('The evaluation run ID'),
+        wait_seconds: z.number().int().min(0).max(60).optional().describe('How long to wait for a running run to finish (default 20; 0 = answer at once)'),
+    }, async (args) => {
+        try {
+            // Waiting here instead of being called every few seconds: each call is a model turn for an agent.
+            const deadline = Date.now() + 1000 * (args.wait_seconds ?? 20);
+            let run = await evals.getRunInOrg(args.run_id);
+            while (run.status !== 'completed' && run.status !== 'failed' && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, Math.min(5000, deadline - Date.now())));
+                run = await evals.getRunStatus(args.run_id);
+            }
+            return success(run);
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('eval_gate_verdict', 'Judge a finished run like the CI gate: pass rate = passed/total, optional p95 limit, failed runs fail by default.', {
+        run_id: z.string(),
+        min_pass_rate: z.number().min(0).max(1).optional(),
+        max_p95_ms: z.number().optional(),
+        error_policy: z.enum(['block', 'warn']).optional(),
+        fail_on_error: z.boolean().optional(),
+    }, async (args) => {
+        try {
+            const run = await evals.getRunInOrg(args.run_id);
+            if (run.status !== 'completed' && run.status !== 'failed')
+                return success({ finished: false, status: run.status });
+            return success({ finished: true, ...gateVerdict(run, { minPassRate: args.min_pass_rate, maxP95Ms: args.max_p95_ms, errorPolicy: args.error_policy, failOnError: args.fail_on_error }) });
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_eval_results', 'Per-case results of an evaluation run. response_format "concise" (default) keeps pass/fail, scores and failed criteria; "detailed" adds transcripts, tool calls and evidence.', {
+        run_id: z.string().describe('The evaluation run ID'),
+        response_format: z.enum(['concise', 'detailed']).optional(),
+        failed_only: z.boolean().optional().describe('Only cases that did not pass'),
+    }, async (args) => {
+        try {
+            await evals.getRunInOrg(args.run_id);
+            let results = await evals.getRunResults(args.run_id);
+            if (args.failed_only)
+                results = results.filter((r) => r.passed !== true);
+            if (args.response_format !== 'detailed') {
+                results = results.map((r) => ({
+                    result_id: r.result_id, item_name: r.item_name, item_type: r.item_type, status: r.status, passed: r.passed,
+                    scores: r.scores, failed_criteria: Array.isArray(r.criteria_scores) ? r.criteria_scores.filter((c) => !c.passed) : undefined,
+                    failed_rules: Array.isArray(r.rubric_scores) ? r.rubric_scores.filter((c) => !c.passed) : undefined,
+                    error: r.error,
+                }));
+            }
+            return success(results);
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('get_bot_context', 'Everything the evaluator knows about an agent: prompt, tools, knowledge bases, LLM config.', { bot_id: z.string().describe('The agent ID') }, async (args) => {
+        try {
+            await evals.assertAgentInOrg(args.bot_id);
+            return success(await evals.getBotContext(args.bot_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('eval_trends', 'Pass rate and latency over an agent\'s past runs, with drift when the pass rate dropped by 0.1 or more.', { agent_id: z.string(), test_set_id: z.string().optional(), limit: z.number().int().min(1).max(200).optional() }, async (args) => {
+        try {
+            await evals.assertAgentInOrg(args.agent_id);
+            return success(await evals.trends(args.agent_id, args.test_set_id, args.limit));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('compare_eval_runs', 'Pass rate and p95 latency difference between two runs.', { run_a: z.string(), run_b: z.string() }, async (args) => {
+        try {
+            await evals.getRunInOrg(args.run_a);
+            await evals.getRunInOrg(args.run_b);
+            return success(await evals.compareRuns(args.run_a, args.run_b));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('eval_report_link', 'Have the evaluations service render the PDF report of a completed run; returns a link valid for 15 minutes.', { run_id: z.string(), force: z.boolean().optional().describe('Render again instead of reusing the last report') }, async (args) => {
+        try {
+            await evals.getRunInOrg(args.run_id);
+            return success(await evals.exportReport(args.run_id, args.force));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('eval_quality_metrics', 'Voice quality metrics a test item may require (names for expected.voice.required_metrics).', {}, async () => {
+        try {
+            return success(await evals.qualityMetrics());
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_prod_calls', 'Ingested production voice calls of an agent, newest first; search matches the transcript.', { agent_id: z.string(), search: z.string().optional(), limit: z.number().int().min(1).max(200).optional() }, async (args) => {
+        try {
+            await evals.assertAgentInOrg(args.agent_id);
+            return success(await evals.prodCalls(args.agent_id, { search: args.search, limit: args.limit }));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('promote_prod_call', 'Add an ingested production voice call as a test item to the agent\'s "Regressions (review)" test set.', { session_id: z.string() }, async (args) => {
+        try {
+            const call = await evals.prodCall(args.session_id);
+            if (call.bot_id)
+                await evals.assertAgentInOrg(String(call.bot_id));
+            return success(await evals.promoteProdCall(args.session_id));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('evaluate_transcript', 'Grade a replayed conversation against a baseline with the agent\'s stored evaluator (paid model calls).', {
+        agent_id: z.string(),
+        baseline_transcript: z.array(z.object({ sender: z.enum(['user', 'bot']), text: z.string() })),
+        replay_transcript: z.array(z.object({ sender: z.enum(['user', 'bot']), text: z.string() })),
+    }, async (args) => {
+        try {
+            await evals.assertAgentInOrg(args.agent_id);
+            return success(await evals.evaluateTranscript(args));
+        }
+        catch (err) {
+            return error(err);
+        }
+    });
+    reg.tool('list_evaluator_configs', 'Stored evaluator configs of an agent (which judges and rubric a run uses).', { agent_id: z.string() }, async (args) => {
+        try {
+            await evals.assertAgentInOrg(args.agent_id);
+            return success(await evals.listEvaluatorConfigs(args.agent_id));
         }
         catch (err) {
             return error(err);
@@ -653,8 +1887,9 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Rubric tools
     // ---------------------------------------------------------------------------
-    server.tool('list_rubrics', 'List evaluation rubrics, optionally filtered by agent', { agent_id: z.string().optional().describe('Filter rubrics by agent ID') }, async (args) => {
+    reg.tool('list_rubrics', 'Evaluation rubrics (behaviour rules an agent is graded on) of one agent.', { agent_id: z.string().describe('Agent ID (rubrics of other orgs are never listed)') }, async (args) => {
         try {
+            await evals.assertAgentInOrg(args.agent_id);
             const result = await rubrics.listRubrics(args.agent_id);
             return success(result);
         }
@@ -662,30 +1897,32 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('get_rubric', 'Get details of a specific rubric', { rubric_id: z.string().describe('The rubric ID') }, async (args) => {
+    reg.tool('get_rubric', 'One rubric with its rules.', { rubric_id: z.string().describe('The rubric ID') }, async (args) => {
         try {
-            const result = await rubrics.getRubric(args.rubric_id);
+            const result = await rubricInOrg(args.rubric_id);
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('create_rubric', 'Create a new evaluation rubric', {
+    reg.tool('create_rubric', 'Create a rubric: 3 to 6 behaviour rules an agent must follow, each with a severity.', {
         name: z.string().describe('Rubric name'),
-        rules: z.array(z.record(z.unknown())).describe('Array of rubric rules'),
+        rules: z.array(rubricRuleSchema).describe('The rubric rules'),
         agent_id: z.string().optional().describe('Agent ID to associate the rubric with'),
         description: z.string().optional().describe('Rubric description'),
         severity_definitions: z.record(z.string()).optional().describe('Severity level definitions'),
     }, async (args) => {
         try {
-            const input = { name: args.name, rules: args.rules };
+            const input = { name: args.name, rules: args.rules.map(toRubricRule) };
             if (args.agent_id !== undefined)
                 input.agent_id = args.agent_id;
             if (args.description !== undefined)
                 input.description = args.description;
             if (args.severity_definitions !== undefined)
                 input.severity_definitions = args.severity_definitions;
+            if (args.agent_id)
+                await evals.assertAgentInOrg(args.agent_id);
             const result = await rubrics.createRubric(input);
             return success(result);
         }
@@ -693,11 +1930,11 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('update_rubric', 'Update an existing rubric', {
+    reg.tool('update_rubric', 'Change a rubric; this saves a new version.', {
         rubric_id: z.string().describe('The rubric ID'),
         name: z.string().optional().describe('Updated name'),
         description: z.string().optional().describe('Updated description'),
-        rules: z.array(z.record(z.unknown())).optional().describe('Updated rules'),
+        rules: z.array(rubricRuleSchema).optional().describe('Updated rules'),
     }, async (args) => {
         try {
             const input = {};
@@ -706,7 +1943,8 @@ export function registerTools(server, client) {
             if (args.description !== undefined)
                 input.description = args.description;
             if (args.rules !== undefined)
-                input.rules = args.rules;
+                input.rules = args.rules.map(toRubricRule);
+            await rubricInOrg(args.rubric_id);
             const result = await rubrics.updateRubric(args.rubric_id, input);
             return success(result);
         }
@@ -714,8 +1952,9 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('delete_rubric', 'Delete a rubric', { rubric_id: z.string().describe('The rubric ID to delete') }, async (args) => {
+    reg.tool('delete_rubric', 'Delete a rubric.', { rubric_id: z.string().describe('The rubric ID to delete') }, async (args) => {
         try {
+            await rubricInOrg(args.rubric_id);
             await rubrics.deleteRubric(args.rubric_id);
             return success({ deleted: true, rubric_id: args.rubric_id });
         }
@@ -723,8 +1962,9 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('list_rubric_versions', 'List all versions of a rubric', { rubric_id: z.string().describe('The rubric ID') }, async (args) => {
+    reg.tool('list_rubric_versions', 'Saved versions of a rubric.', { rubric_id: z.string().describe('The rubric ID') }, async (args) => {
         try {
+            await rubricInOrg(args.rubric_id);
             const result = await rubrics.listVersions(args.rubric_id);
             return success(result);
         }
@@ -735,8 +1975,9 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Test set tools
     // ---------------------------------------------------------------------------
-    server.tool('list_test_sets', 'List test sets, optionally filtered by agent', { agent_id: z.string().optional().describe('Filter test sets by agent ID') }, async (args) => {
+    reg.tool('list_test_sets', 'Evaluation test sets (scenarios an agent is tested on) of one agent.', { agent_id: z.string().describe('Agent ID (test sets of other orgs are never listed)') }, async (args) => {
         try {
+            await evals.assertAgentInOrg(args.agent_id);
             const result = await testSets.listTestSets(args.agent_id);
             return success(result);
         }
@@ -744,27 +1985,29 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('get_test_set', 'Get details of a specific test set', { test_set_id: z.string().describe('The test set ID') }, async (args) => {
+    reg.tool('get_test_set', 'One test set with its items (single turns, scenarios, voice simulations).', { test_set_id: z.string().describe('The test set ID') }, async (args) => {
         try {
-            const result = await testSets.getTestSet(args.test_set_id);
+            const result = await testSetInOrg(args.test_set_id);
             return success(result);
         }
         catch (err) {
             return error(err);
         }
     });
-    server.tool('create_test_set', 'Create a new test set', {
+    reg.tool('create_test_set', 'Create a test set for an agent: items with inputs and success criteria.', {
         name: z.string().describe('Test set name'),
-        items: z.array(z.record(z.unknown())).describe('Array of test items'),
+        items: z.array(testItemSchema).describe('The test items'),
         agent_id: z.string().optional().describe('Agent ID to associate the test set with'),
         description: z.string().optional().describe('Test set description'),
     }, async (args) => {
         try {
-            const input = { name: args.name, items: args.items };
+            const input = { name: args.name, items: args.items.map(toTestItem) };
             if (args.agent_id !== undefined)
                 input.agent_id = args.agent_id;
             if (args.description !== undefined)
                 input.description = args.description;
+            if (args.agent_id)
+                await evals.assertAgentInOrg(args.agent_id);
             const result = await testSets.createTestSet(input);
             return success(result);
         }
@@ -772,11 +2015,11 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('update_test_set', 'Update an existing test set', {
+    reg.tool('update_test_set', 'Change a test set; this saves a new version.', {
         test_set_id: z.string().describe('The test set ID'),
         name: z.string().optional().describe('Updated name'),
         description: z.string().optional().describe('Updated description'),
-        items: z.array(z.record(z.unknown())).optional().describe('Updated test items'),
+        items: z.array(testItemSchema).optional().describe('Updated test items'),
     }, async (args) => {
         try {
             const input = {};
@@ -785,7 +2028,8 @@ export function registerTools(server, client) {
             if (args.description !== undefined)
                 input.description = args.description;
             if (args.items !== undefined)
-                input.items = args.items;
+                input.items = args.items.map(toTestItem);
+            await testSetInOrg(args.test_set_id);
             const result = await testSets.updateTestSet(args.test_set_id, input);
             return success(result);
         }
@@ -793,8 +2037,9 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('delete_test_set', 'Delete a test set', { test_set_id: z.string().describe('The test set ID to delete') }, async (args) => {
+    reg.tool('delete_test_set', 'Delete a test set.', { test_set_id: z.string().describe('The test set ID to delete') }, async (args) => {
         try {
+            await testSetInOrg(args.test_set_id);
             await testSets.deleteTestSet(args.test_set_id);
             return success({ deleted: true, test_set_id: args.test_set_id });
         }
@@ -802,8 +2047,9 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('list_test_set_versions', 'List all versions of a test set', { test_set_id: z.string().describe('The test set ID') }, async (args) => {
+    reg.tool('list_test_set_versions', 'Saved versions of a test set.', { test_set_id: z.string().describe('The test set ID') }, async (args) => {
         try {
+            await testSetInOrg(args.test_set_id);
             const result = await testSets.listVersions(args.test_set_id);
             return success(result);
         }
@@ -814,7 +2060,7 @@ export function registerTools(server, client) {
     // ---------------------------------------------------------------------------
     // Export tools
     // ---------------------------------------------------------------------------
-    server.tool('export_eval_markdown', 'Export evaluation results as a structured markdown file with conversations, scores, and criteria', {
+    reg.tool('export_eval_markdown', 'Export evaluation results as a structured markdown file with conversations, scores, and criteria', {
         run_id: z.string().describe('The evaluation run ID'),
         output_path: z.string().optional().describe('Output file path (defaults to current directory)'),
     }, async (args) => {
@@ -826,7 +2072,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('export_eval_report', 'Generate a branded PDF evaluation report with cover page, scores, and per-item details', {
+    reg.tool('export_eval_report', 'Generate a branded PDF evaluation report with cover page, scores, and per-item details', {
         run_id: z.string().describe('The evaluation run ID'),
         output_path: z.string().optional().describe('Output file path (defaults to current directory)'),
     }, async (args) => {
@@ -838,7 +2084,7 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
-    server.tool('export_agent_card', 'Generate a branded PDF agent card with system prompt, tools, KBs, LLM config, and evaluation history', {
+    reg.tool('export_agent_card', 'Generate a branded PDF agent card with system prompt, tools, KBs, LLM config, and evaluation history', {
         agent_id: z.string().describe('The agent ID'),
         output_path: z.string().optional().describe('Output file path (defaults to current directory)'),
     }, async (args) => {
@@ -850,5 +2096,6 @@ export function registerTools(server, client) {
             return error(err);
         }
     });
+    return reg;
 }
 //# sourceMappingURL=tools.js.map