Create a Convocore agent (advanced/raw). Prefer create_agent_from_template for website/branded agents. Always node-based: enableNodes is forced true; put the main prompt in systemPrompt (or nodes[0].instructions) — do NOT use vg_instructions (API rejects that field). Default chat model is always claude-haiku-4-5-20251001 (Claude Haiku 4.5) on vg_defaultModel + nodes[0].llmConfig.modelId. UI Engine flags optional via vg_enableUIEngine*. Lead notify: use funnelConfig (AI Funnel + lead scoring + email recipients) — do NOT create custom HTTP webhook tools for sales alerts. Sets nodes[0].kb.enabled for auto RAG with maxChunks=3 and vgOptions.maxChunkSize=512 — still bake critical facts into systemPrompt. Do not raise chunk size or chunk count unless the user asks.

PRIMARY way to create chat+voice agents. Workspace is resolved internally from MCP configuration/workspace secret context (no workspaceId input). Uses strict template invariants: agentPlatform=vg, enableNodes=true, vg_enableUIEngine=true, vg_enableUIEngineForms=true + form notify, default funnelConfig (lead scoring + email notify), nodes[0].kb.enabled (auto RAG, maxChunks=3, vgOptions.maxChunkSize=512), nodes[0].toolsIds includes built-in web-search, chat model always claude-haiku-4-5-20251001 (Claude Haiku 4.5), standard prompt clauses. vg_* overrides blocked from additionalConfig. NON-SALES agents (registration, internal, support-only): pass leadCapture=false and appendStandardPromptClauses=false (and attachWebSearchTool=false if it must not browse) so no sales text, funnel or lead forms are added. CRITICAL: bake scraped ground-truth AND a labeled image catalog (after read_image on real photos) into systemPrompt — KB alone is not enough. Pass ownerNotifyEmails so the funnel can email sales. Do NOT invent HTTP notify-sales webhooks. Run 8–12 turn tests before declaring done. Response includes prototypeUrl / tryItUrl — ALWAYS paste that link for the user to try the agent. Pattern: https://app.convocore.ai/{eu|na}/prototype/{agentId}. NEVER invent app.convocore.ai/agents/...

Retrieve details of a specific Convocore agent. Main prompt is always nodes[0].instructions (enableNodes is true for agents created via this MCP). Legacy vg_instructions only if nodes are absent on a very old agent. ownerID is the workspaceId and is read-only. Response includes prototypeUrl / tryItUrl — share that public demo with the user (https://app.convocore.ai/{eu|na}/prototype/{agentId}). Never invent /agents/ links.

Update an existing Convocore agent (PATCH). For large prompt edits prefer patch_agent_prompt. Main prompt: use systemPrompt → start node instructions. NEVER send vg_instructions or vg_systemPrompt. Do NOT pass nodes[] unless you are changing nodes — omit it for title/UI/funnel/model updates. Partial nodes[] are GET-merged by id; a toolsIds-only start node cannot blank instructions, and toolsIds in a patch are only ever ADDED (tools attached on the dashboard are kept). To detach tools pass allowRemoveTools=true. Lead notify: funnelConfig (steps + notificationRules.recipients). UI Engine: vg_enableUIEngine* + vg_uiEngineChannelConfig. ownerID is read-only.

Performs string replacements in the start-node prompt (or proactiveMessage / customCSS). USE THIS instead of update_agent when the prompt is large and you only need to change a specific section. If get_agent returns empty instructions, this tool REFUSES a surgical patch — it will NOT replace the whole prompt with new_string. Workflow: get_agent → copy the exact span into old_string → new_string is the replacement. Only omit old_string when the field is truly empty and new_string is the FULL prompt. target=auto patches the start node instructions. Never writes vg_instructions (API rejects it). sync_mirrors defaults false.

Delete a Convocore agent permanently

List accessible agents. Default mode="compact" returns only short fields (id, title, description, theme, flags, timestamps) so responses stay token-cheap — use this to find recent agents. mode="full" returns complete agent documents (nodes/prompts/voice/etc.) and is heavy; prefer get_agent for one agent, or search_agents for filtered lookup. Compact defaults limit=25 when omitted.

Search/filter Convocore agents. Default mode=compact (short fields only). Use mode=full only when you need complete agent docs. Prefer list_agents (compact) for recent agents without a query.

Export an agent template for backup or migration. For import/export, rely on these dedicated OpenAPI routes instead of trying to manually construct the template shape.

Import an agent from a template produced by export_agent / the OpenAPI export-template route. The template shape is complex; do not invent it manually unless the user provides an exact exported object.

Get agent usage statistics and credits consumed

List conversations for an agent (newest first). Default mode=compact (id/ts/summary/user/origin — no messages). mode=full returns raw list rows. For message bodies use get_conversation or get_conversations_bulk. Cursor pagination: hasMore + nextCursor; do NOT bump page alone. Max limit=20.

Create a new conversation for an agent

Get details of a single conversation

Patch fields on the light conversation document. This does NOT replace the stored turn/message history. To replace transcript turns, use update_conversation_messages.

Replace the stored message turn history for a conversation using PATCH /agents/{agentId}/convos/{convoId}/messages. This overwrites voiceglow/{agentId}/convos/{convoId}/convo/JSON_STRING with the provided turns array. Set updateConversationMetadata=true (default) to also refresh messagesNum, lastMessage, firstMessageTS, lastMessageTS, and lastModified on the light conversation doc. Because this is a full replacement, confirmReplace must be true.

Delete a conversation

Export conversations for an agent (Postgres mirror). Requires a paid workspace (hasEverPaid === true); billed against monthly export quota. Supports cursor pagination via cursor/nextCursor/hasMore, or selected mode via convoIds. Formats: json|csv.

Export a single conversation. Requires a paid workspace (hasEverPaid === true); billed against monthly export quota.

Assign a conversation to a user for manual delegation

Fetch lean summaries for many conversation IDs in one call (fan-out GETs with concurrency). Returns {ID, summary, ts, capturedVariables, userName, origin} per convo. Max 50 IDs per call — chunk larger audits. Workflow: list_conversations with cursor to collect IDs, then this tool (do NOT loop get_conversation).

MCP-side filter over conversations (NOT a SQL analytics API). Cursor-pages list_conversations then bulk-gets details when filters need summary/capturedVariables/userName. Bounded by maxScan (default 200). Use for audits like summaryContains or capturedVariableExists. True server-side filters (hasQuote, eventDateWithin) need a future backend endpoint.

Fetch usage/credits for many agents in one call (fan-out). Max 20 agentIds. Optional shared date range.

Fetch many KB documents in one call (fan-out). Max 30 docIds. Default returns compact metadata + chunksPreview; set includeContent=true for full bodies.

PREFERRED for adding many website pages to an agent KB. Pass up to 50 URLs; the Convocore KB router scrapes them (scrapeContent=true). Do NOT web-fetch/scrape_url then paste content into create_kb_doc — that is slow and duplicates work. mode=per_url (default): one KB doc per URL. mode=batch: one API call with urls[]. For a whole site prefer create_kb_doc sourceType=sitemap. Scraping is async — poll list_kb_docs/get_kb_doc for status.

Add one knowledge base source (VG agents). For many page URLs use create_kb_from_urls instead. For websites: sourceType=url with urls[] + scrapeContent=true (KB router scrapes). For whole-site: sourceType=sitemap + sitemapUrl + maxPages + scrapeContent=true. sourceType=doc only for raw text you already have — do not paste web-fetched HTML here.

List knowledge base documents for an agent. Default mode=compact (id/name/status/urls — NO content bodies). Use mode=full only if you need every list field; prefer get_kb_doc for one document body.

Get a single knowledge base document

Update a knowledge base document (VG agents only). For large document bodies prefer patch_kb_doc (Cursor-style exact old_string→new_string) instead of rewriting the entire content field.

Performs string replacements in a knowledge-base document — same idea as Cursor StrReplace for files. USE THIS instead of update_kb_doc when the document body is large and you only need to change a specific section. Workflow: get_kb_doc → copy the span into old_string (include enough surrounding context to make it unique) → new_string is the replacement → this tool patches content (or name) and PATCHes the KB doc. Prefer an exact copy from get_kb_doc; minor whitespace/line-ending drift is tolerated as a fallback. Prefer this over rewriting the entire content field. Only use replace_all=true when you intentionally want every occurrence changed.

Delete a knowledge base document (VG agents only)

Get knowledge base statistics for an agent (VG agents only)

Validate and/or scrape HTTP(S) URLs. DEFAULT mode=check: fast ping of one or many links/images (up to 20) — returns status (200/301/404/etc), ok, content-type, final URL after redirects. Use this to verify widget images, logos, CDN assets, booking links, or any URL before putting it on an agent. mode=scrape: full Convocore crawler scrape of ONE page (waits up to ~120s) for text/colours/favicon/images when building branded agents. After scrape, CHECK image URLs then call read_image on every important photo so you know what each picture is before putting it in the agent prompt. Default useProxy=false (~1 credit). CRITICAL — proxy: ONLY if a normal (useProxy=false) scrape fails/blocks AND the user explicitly confirms. Proxy is MUCH more expensive (~60 credits/page) and CONSUMES Convocore workspace credits. Requires useProxy=true + confirmExpensiveProxy=true. Never enable proxy proactively. Do NOT use scrape for KB ingest (use create_kb_from_urls). Workspace is resolved internally — never pass workspaceId.

MUST CALL whenever the user asks to deploy/embed/add their agent to a website, get the widget script, iframe code, popup chat bubble, or 'where is the code'. Returns a ready-to-paste HTML snippet with the real agent ID and region filled in (popup, full-width inline, modal, or React voice-only example). Do NOT redirect the user to the dashboard Channels/Deployment tab instead of returning this code. If agentId is unknown, call list_agents first, then call this tool.

MUST CALL FIRST whenever the user asks to style/restyle/theme the Convocore (vg) chat widget — e.g. 'change the icons to black', 'make the header purple', 'recolor the send button', 'theme the widget dark', 'change the user bubble color', 'restyle the proactive teaser'. Returns the FULL authoritative styling guide (the same SYSTEM_PROMPT used by Convocore's server-side AI CSS generator) including: (a) the global output rules (always wrap in ```css, always !important, never invent class names), (b) the CRITICAL compound-element CASCADE rule for color/icon changes (.vg-foo, .vg-foo , .vg-foo svg, .vg-foo path { color + stroke }), (c) hard constraints (don't color .vg-message-inner-container-human, don't hide the input, etc.), (d) the COMPLETE class & id map (.vg- selectors for every part of the widget — header, footer input, send button, messages, proactive bubble, notices, cards, voice mode, live agents, etc.), (e) the NextUI/Tailwind color system, and (f) ready-made selector recipes mapping plain-English asks to selectors. If you pass agentId, the agent's current customCSS is appended so the model can refine/extend it instead of duplicating rules. After calling this, generate CSS that strictly follows the guide, then call update_agent_custom_css to persist it.

Read the agent's current customCSS field (the per-agent CSS override applied to the chat widget). Returns the raw CSS string (empty string if none set). Use this before editing so you can produce a merged result for update_agent_custom_css.

Cheap probe of a file (path / url / base64). Returns kind, mime, size, page count (PDF), sheet names (XLSX), line count (text), or pixel dimensions (image), plus an estimated token cost. ALWAYS call this first on anything larger than a few KB — use it to decide which read_* tool to call and which slice (pages / sheet / range) to request, so you don't blow the context window.

Read a plain-text file (.txt, .md, .json, .csv, .yaml, .log, code, etc.) from path / url / base64. Returns UTF-8 text plus a truncation flag and token estimate. Honors an optional maxBytes cap. For .docx use read_docx, for .pdf use read_pdf, for .xlsx use read_spreadsheet.

Extract text from a PDF (path / url / base64). Page-aware: pass pages as a string range like "1-3,5,7-9" or an explicit array to read only the pages you need. Output is split per page with --- page N --- headers. Auto-truncates if the result would exceed the per-call token budget. Always inspect_file first to learn totalPages.

Extract text from a .docx Word document (path / url / base64). Set asMarkdown=true to preserve headings, lists, links and bold/italic. Legacy .doc is NOT supported — convert to .docx first.

Read an Excel (.xlsx / .xlsm / .xls) or CSV file. Two-step pattern: (1) call WITHOUT sheet to list sheet names, (2) call again with sheet to read that sheet. Optional A1-style range (e.g. "A1:D50") and format ('markdown' default, or 'csv' / 'json'). headerRow=true (default) treats row 1 as keys when format='json'.

Load an image (PNG / JPEG / WebP / GIF / SVG / TIFF / BMP / HEIC) from path / url / base64 and return it as a vision-ready MCP image content block so YOU can see the pixels. REQUIRED after scraping a website: call this with url= on every high-value product/room/treatment/team photo, then write what you saw + the exact URL into the agent systemPrompt catalog. Do not skip this and dump unlabeled URLs. Auto-normalizes: rasterizes SVG, downscales anything larger than maxDimension (default 2048px), and re-encodes to PNG (or JPEG when needed for size).

End-to-end shortcut: read any supported file (PDF / DOCX / XLSX / CSV / TXT / MD / JSON / HTML) and create a Knowledge Base document on the target agent in one call. The file is parsed locally to text/markdown and pushed to the agent's KB via create_kb_doc with sourceType='doc'. Use pages for PDFs and sheet for spreadsheets to control what gets ingested. Images are NOT supported here (they need OCR or vision — use read_image instead).

Overwrite the agent's customCSS field with new CSS that styles the chat widget. IMPORTANT: this REPLACES the existing customCSS value — always pass the FULL merged CSS (existing + your new rules), not just the delta. Workflow: (1) call get_widget_css_styling_guide to load selectors + rules, (2) optionally call get_agent_custom_css to read what's already there, (3) generate the merged CSS following the guide, (4) call this tool to persist. Pass an empty string to clear all customCSS for the agent.

Pause for the given number of seconds and then return. Useful when you need to wait between actions (e.g. polling a job, rate-limiting, giving an external system time to settle). Range: 0–300 seconds.

Execute a shell command on the host machine where the MCP server is running and return stdout, stderr, and the exit code. Runs through the platform default shell (cmd.exe on Windows, /bin/sh on Unix). Use for simple system tasks like checking versions, listing files, or running short scripts. NOTE: this tool has full access to the host shell with the MCP process privileges — only run commands you trust.

List every TTS voice provider Convocore supports (elevenlabs, deepgram, cartesia, rime-ai, openai, google-cloud, google-live (Gemini Live), ultravox, minimax, playht, azure). For each provider returns the workspace secret-key name (e.g. ELEVENLABS_API_KEY) and a requiresWorkspaceApiKey flag indicating whether the platform has a server-side fallback or the workspace must BYOK. Read-only — does NOT consume credits.

List the available TTS models for a given provider (e.g. "aura-2" for Deepgram, "eleven_multilingual_v2" for ElevenLabs). Use the returned modelId values with search_voices / list_provider_voices to filter the catalog. Read-only — does NOT consume credits.

Unified voice search across one or more TTS providers. Every result is normalized to { voiceId, name, provider, previewUrl, filters: { accent, gender, useCase, language } }. Use this when the user asks for a voice by gender / language / accent without caring which provider. Read-only — does NOT consume credits.

Browse the voice catalog for ONE specific provider with the same filter params as search_voices. Use when the user has already chosen a provider (e.g. "show me ElevenLabs male British voices"). Read-only — does NOT consume credits.

Fetch full metadata + a preview MP3 URL for a single voice. Use after the user picks one from search_voices / list_provider_voices, or when they paste a voice ID. Read-only — does NOT consume credits.

Import a Twilio SMS/voice number you already own into the workspace (uses your Twilio account credentials). This is NOT a WhatsApp Cloud API connection; do not use it for waNumbers/Meta WhatsApp. Pass the full request body for /utils/import-twilio-number as an object — typically includes your Twilio account SID, auth token, the phone number, optional agentId and capabilities.

Release (delete) a Twilio SMS/voice number from the workspace. This does not remove WhatsApp Cloud API waNumbers. Pass the full request body for /utils/twilio/release-number as an object — typically includes phoneNumber or phoneNumberSid.

Repair / re-sync the Twilio SMS/voice webhook configuration for a number (useful when call/SMS routing breaks). This does not check WhatsApp Cloud API health. Pass the full request body for /utils/twilio/check-number as an object — typically includes phoneNumber or phoneNumberSid.

Assign a Twilio number to an agent for SMS handling. This is SMS only; WhatsApp routing uses waNumbers/{phoneId}, origin "whatsapp", and Meta Cloud API. Pass the full request body for /utils/twilio/sync-sms as an object — typically includes phoneNumber (or sid) and agentId.

Run ONE agent turn over the Convocore /interact WebSocket and return the streamed result aggregated into a single response. Opens a WSS connection to wss://-gcp-api.vg-stuff.com/interact, sends one InteractObject (agentId + convoId + bucket + prompt + optional context), collects every chunk (text + UI-engine + actions + metadata + sync_chat_history) until the server closes (code 1000) or the timeout fires, then returns: { assistantText, uiEngineEnabled, uiEngineSnapshot, uiEngineSummary, actions, metadata, turns, closeCode, durationMs, timedOut, chunkCount, chunks? }.

USAGE:

• Use the SAME convoId across turns to keep history; use a fresh one to start a new conversation.

• prompt: "start" triggers the agent's initial greeting (no user message added).

• prompt: "@cancel:<reason>" cancels an in-flight turn (rarely useful from a single MCP call).

• prompt: "@rewind:<nodeId>" rewinds a node-based agent.

• For images, set messageType="visual" and pass visualPayload.

• bucket is auto-derived from CONVOCORE_API_REGION; only override if you really mean to talk to the other region.

• Set raw: true to include every streamed chunk (debug frames, chunkIndex, every UI Engine snapshot, etc.) when you need the full trace. Default keeps the response token-cheap.

• TESTING: set isTest: true for test chats. Pass toolTest: { toolId, toolName, mode: validate|generate-and-test } to exercise one HTTP tool (or use dedicated test_agent_tool). Pass variablesOverrides / initNodesOptions to trial variables without permanently changing them.

• For a direct HTTP dry-run of a tool's serverUrl use test_agent_tool_request. For multi-turn suites use run_agent_auto_test.

INTERPRETING THE RESPONSE:

• When uiEngineEnabled: false, the agent streamed plain Markdown — read assistantText.

• When uiEngineEnabled: true, the agent streamed UI Engine snapshots — read uiEngineSnapshot (parsed final TurnProps) and uiEngineSummary (compact per-message summary). assistantText may be empty in this mode.

• To force plain text on a UI-Engine-enabled agent for one turn, pass disableUiEngine: true.

UI ENGINE — TWO LAYERS YOU MUST KEEP STRAIGHT:

LAYER 1 — AGENT LLM OUTPUT CONTRACT (what the tested agent is INSTRUCTED to emit):

• The agent's system prompt forces its LLM to output ONE JSON ARRAY of message objects: [ { "type": "text"|"choice"|"visual"|"cardV2"|"carousel"|"iFrame"|"form"|"input", "payload": {...} }, ... ]

• The very first character MUST be "[" and the very last MUST be "]". No prose, no ```json fences, no leading/trailing newlines.

• Preferred message order in the array: text intro -> card / carousel / visual -> iFrame (if video URL exists) -> choice buttons (CTAs).

• Buttons / image URLs / iFrame URLs MUST come from KB or tool output. NEVER invent URLs. If KB has nothing, omit the button or fall back to text.

• select / radio fields MUST include a non-empty options[] of { value, label }. If real options are unknown, use type "text" or "textarea" instead.

• form / input messages WEB CHANNELS ONLY (web-chat / text). On voice / telephony / WhatsApp / SMS / messaging the server strips them.

• WhatsApp extra rule: only use visual / cardV2 / carousel when you have a verified image URL from KB or a tool — otherwise use text only.

LAYER 2 — WIRE FORMAT (what arrives over the /interact WebSocket):

• When chunk.ui_engine === true, chunk.chunk is a JSON-stringified TurnProps SNAPSHOT of the bot turn so far.

• SNAPSHOTS ARE OVERWRITING — replace the in-progress turn with the latest parse, never concatenate.

• Parsed shape: { from: "bot", ts, modelId?, messages: ChatMessage[] }.

• Each ChatMessage wraps the agent's array entry: { from: "bot", type, ts, mid?, item: { type, payload } }. So agent emits [{ type, payload }, ...] -> wire wraps each as { ..., item: { type, payload } } inside messages[].

PAYLOAD SHAPES (item.payload): text -> { message } (Markdown supported). choice -> { buttons: [{ name, request: { type: "open_url"|"text", payload: { url|message } } }] }. visual -> { image } (URL ending in .png/.jpg/.jpeg/.webp/.gif/.svg/.avif/.bmp). cardV2 -> { title, imageUrl?, description?: { text }, buttons?: UiEngineButton[] }. carousel -> { cards: CardPayload[] }. iFrame -> { layout: "vertical"|"horizontal", url } (vertical = video embeds, horizontal = general web). form -> { title?, description?, fields: UiEngineInputField[], submitButton?, onSubmit: { type: "submit_form", message? } }. Web channels only. input -> { field: UiEngineInputField, submitOnEnter?, onSubmit: { type: "submit_input", message? } }. Web channels only. UiEngineInputField.type: text|email|password|number|tel|url|textarea|select|checkbox|radio|date|time|datetime-local|file.

WHEN ui_engine === false (or omitted): chunk.chunk is plain Markdown text — append to the in-progress assistant message. TO FORCE PLAIN TEXT on a UI-Engine-enabled agent for one turn: pass disableUiEngine: true on the InteractRequest.

SERVER SANITIZERS YOU SHOULD KNOW (so you do not get surprised when a message disappears):

• form messages with zero valid fields are DROPPED.

• input messages with an invalid field are DROPPED.

• select / radio fields with empty / duplicate / missing-label options are DROPPED.

• any field missing id or label is DROPPED.

For the FULL UI Engine schema (every payload field, validation rules, allowed enums) call get_ui_engine_spec first.

WARNING: This consumes Convocore credits exactly like a real agent turn (LLM + voice + tools). It is NOT a dry-run.

Return the FULL Convocore UI Engine schema (the structured message format agents emit when vg_enableUIEngine: true). ALWAYS CALL THIS FIRST when: (a) testing a UI-Engine-enabled agent via interact_with_agent and you need to validate the output, OR (b) creating / updating an agent that should produce UI Engine output (so the system prompt teaches the LLM to emit valid text / choice / visual / cardV2 / carousel / iFrame / form / input / invoice / calendarBooking messages). Also documents agent feature flags (vg_enableUIEngineForms, vg_enableUIEngineInvoice, vg_enableUIEngineCalendarBooking, vg_uiEngineChannelConfig) used by update_agent to allow/deny which UI elements the agent may show. Returns: meta (streaming + channel-gating + agentFeatureFlags), envelopes (TurnProps / ChatMessage), messageTypes, shared types, rules, and a validationChecklist. Use section to narrow the response: "meta" | "envelopes" | "message_types" | "shared" | "rules" | "checklist" | "primer" | "all" (default). Use messageType to drill into a single message-type schema (e.g. "choice" or "form"). Static knowledge — does NOT hit the API and does NOT consume credits.

Return static Convocore channel-integration schema guidance for MCP clients. Use this before configuring or explaining WhatsApp, Facebook Messenger, Instagram, or SMS routing. It clarifies canonical storage locations, safe update fields, read-only/system-managed fields, credential masking, WhatsApp coexistence/AI behavior settings, Messenger/Instagram page mapping, and why Twilio SMS tools must not be used for WhatsApp Cloud API numbers. Static knowledge — does NOT hit the API.

Return Convocore pricing information so the assistant can quote plans, add-ons, voice/chat cost rules of thumb, credit conversions, and per-model token prices to the user. Use section to narrow the response: "plans", "add_ons", "credits", "rules_of_thumb", "models", "voice_providers", "faq", or "all" (default). When section="models", optionally pass modelFilter (substring match on model name or provider, e.g. "gpt", "claude") to only return matching rows. Static knowledge — does NOT hit the API and does NOT consume credits. Always remind users that prices may change and direct them to https://convocore.ai/pricing for the live numbers.

Read organizations and related membership. Actions: list, search, get, list_clients, list_agents, list_members_and_teams, list_agent_org_clients. List/search actions default mode=compact (short fields). Use mode=full only when you need complete objects; prefer action=get for one org. Does NOT create/update/delete — use orgs_write. For end-user client accounts use clients_read.

Create/update/delete organizations or assign/unassign an agent to an org. Actions: create, update, delete, assign_agent. For reads use orgs_write siblings orgs_read. Destructive: delete removes the org and associated clients.

Get the current agency account for this workspace secret (raw document). For branding (logo, colours, fonts, language, login page) use agency_branding get — it is typed and never returns secrets. Distinct from orgs_read (child organizations) and clients_read (end-user client accounts).

Create (upsert with a name) or delete the agency account. To brand it (logo, colour, fonts, language, login page, assets) use agency_branding instead — it validates fields. Domain claims, verification flags, secrets and provider keys cannot be changed here (domains are verified on the dashboard). For org/client CRUD use orgs_write / clients_write.

Read Convocore client accounts (end-user workspaces under an agency/org). Actions: list, get, check_email. For action=list, default mode=compact (id/name/email/orgId). Use mode=full only when you need complete client objects; prefer action=get for one client. Not for organizations (use orgs_read) or CRM leads (use leads_read).

Create/update/delete whitelabel client accounts (people who log into the client portal). Actions: create, update, delete. clientData fields are listed and described in the schema: login (email, dashboardPassword), which agents they see (widgetIDs), portal tabs (canAccess), channels / integrations they may use, org membership, permissions and notifications. For reads use clients_read.

Read CRM leads for an agent. Actions: list, get, export, export_filtered. For action=list, default mode=compact (id/name/email/phone/ts — no metaData blobs). Use mode=full only when you need complete lead objects; prefer action=get for one lead. Does not create/update — use leads_write. Not for client accounts (clients_read).

Create/update/delete/import CRM leads. Actions: create, update, delete, delete_many, import_bulk, magic_import, clear_all, delete_group. Destructive: clear_all deletes every lead on the agent.

List HTTP/API tools saved on a Convocore agent (serverUrl integrations). These are NOT MCP tools. A saved tool is only callable when its id is also in a node toolsIds (see get_agent). For MCP catalog discovery use search_mcp_tools. To test a tool use test_agent_tool or test_agent_tool_request.

Get one Convocore agent HTTP tool by toolId (includes fields, serverUrl, method). Does not call the remote URL — use test_agent_tool_request for that.

Add an HTTP/API tool to a Convocore agent. Requires tool.name + tool.description. INPUTS — either (a) tool.variablesIds: ids of existing agent variables (create_agent_variable first), or (b) tool.fields[]: each entry needs key (the argument name — NOT "name"), type (string|number|boolean), in (body|query|header|path), plus description and required. REQUEST — simple tools: method + serverUrl (inputs are sent by their "in" location). Exact request shape: tool.httpRequest = { enabled: true, method, url, headers, query, bodyType: "json", bodyTemplate, bodyTemplateMode: "exact" }. In bodyTemplate/headers/query/url reference a variable with {{var:VARIABLE_ID}}; a value that is only that token keeps its number/boolean type. Fixed values are written literally. SECRETS — store an API key as an environment variable (create_agent_variable with isEnv: true; the value lives in defaultValue) and reference it with {{var:ID}}. Env variables must NOT be listed in variablesIds: they are resolved automatically and never shown to the model. An unfilled optional input sends its defaultValue; an input with no value and no default blocks the call with "Unresolved request values". By default the new tool is attached to the start node (nodes[].toolsIds) so the model can call it; pass attachToStartNode: false to skip. Verify with test_agent_tool_request.

Patch an existing Convocore agent HTTP tool by toolId. Pass only fields to change inside tool{}.

Permanently delete a Convocore agent HTTP tool by toolId. Does not delete MCP tools.

List variables on a Convocore agent (env/global/system keys used in prompts and tools). Not MCP variables. Values of environment variables (isEnv) are masked. To trial overrides in a chat turn use interact_with_agent with variablesOverrides / initNodesOptions.

Get one Convocore agent variable by variableId. The value of an environment variable (isEnv) is masked.

Add a variable to a Convocore agent. Typical fields: key, type, defaultValue, description, in (body|query|header|path), required, isEnv, isGlobal. AI inputs: the model fills them; list their ids in a tool variablesIds. An optional input that is not filled sends its defaultValue. Environment variables (isEnv: true) hold fixed config/secrets: the value is stored in defaultValue, is never shown to the model, and is referenced in a tool request as {{var:VARIABLE_ID}} — do not add them to variablesIds. To keep a secret out of this chat, create it with a placeholder defaultValue and have the owner enter the real value in the dashboard: open the tool editor, type { in a request field (or use Variables), open the variable, keep ENV on and fill "Value". Responses mask env values.

Patch an existing Convocore agent variable by variableId. Pass only fields to change. Never send back a masked env value as defaultValue — omit it to keep the stored value.

Permanently delete a Convocore agent variable by variableId.

Test a Convocore agent HTTP tool via interact WebSocket toolTest mode (validate | generate-and-test). Runs through the agent runtime. For a direct HTTP dry-run against serverUrl use test_agent_tool_request. For multi-turn suites use run_agent_auto_test.

Fire a real HTTP request for a saved tool, bypassing the LLM. Tools with a custom HTTP request (httpRequest.enabled) are replayed exactly as the live runtime sends them: saved bodyTemplate, fixed values, headers, query and environment variables, with fieldOverrides used as the AI-input values (keyed by variable key). Environment variable values and auth headers are masked in the returned request preview. Legacy serverUrl tools are assembled from fields[]. Side effects on the remote API are possible — use carefully.

Start Convocore automated agent test suite (POST /auto-test/run). Modes include tools-only, with-tools, kb-only, full. Returns testId/status/score. Prefer this for broader regression; use test_agent_tool for a single tool.

Clone an existing Convocore agent with optional overrides and carryOver flags (kb, voiceConfig, uiEngineConfig). Never inherits branding or funnel recipients. Prefer this over manually recreating. Distinct from create_agent_from_template / import_agent.

Push an agent-initiated message onto the conversation channel (WhatsApp, Messenger, Instagram, Telegram, SMS, Discord). Does NOT run the LLM — text is sent as-is. Subject to provider rules (e.g. Meta 24h window). Do NOT use update_conversation_messages for channel delivery (that only updates stored history).

List the human review notes on a conversation (a timeline, oldest first). Each note has id, text, createdAt (unix seconds), authorName/authorEmail and source (dashboard | api). get_conversation also returns them as reviewNotes. To find conversations by note, use query_conversations with hasNotes / noteContains.

Add a note to a conversation's notes timeline (visible to the workspace team and clients in the dashboard). Recorded in the workspace Logs with who, IP and time. Max 5000 characters. Prefer this over update_conversation, which cannot change notes.

Replace the text of one existing note. The previous text is kept in the workspace Logs with who edited it, from which IP and when.

Delete one note. Any user with access may delete any note; a full copy is kept in the workspace Logs with who deleted it, from which IP and when. Only call when the user asked to delete that note.

Semantic/vector search over an agent knowledge base (POST .../kb/search). Prefer this to list_kb_docs when looking for content by meaning. For CRUD use create_kb_doc / get_kb_doc / patch_kb_doc.

Delete many KB documents in one call (POST .../kb/delete). Prefer over looping delete_kb_doc. Destructive and irreversible.

Create up to 20 KB documents in one request. For many website URLs prefer create_kb_from_urls. For a single doc use create_kb_doc.

Upload images into the agent KB (optional autoCaption). Backup after you already called read_image and labeled the photos in the system prompt — not a substitute for looking at them.

Get workspace KB document quota usage (GET /workspace/kb-docs/quota). Optional workspaceId; defaults to the authenticated workspace.

Read the WhatsApp "AI rules" of a Convocore agent: the rules that decide whether the AI replies to an inbound WhatsApp message (dashboard: Channels → WhatsApp → AI rules). Returns inboundEngagement (null when never configured — then the AI replies to everything except what the legacy per-number guards block), the defaults, every WhatsApp number assigned to the agent with its phoneId and AI settings (aiPaused, newContactsOnly, coexistenceSettings), and warnings for configurations that keep the AI silent. Meta credentials are never returned. Call this before update_whatsapp_ai_rules / update_whatsapp_number_settings.

Change the WhatsApp "AI rules" of a Convocore agent — when the AI should or should not reply to inbound WhatsApp messages. Partial update: send only the fields to change; lists (triggerPhrases, participantList, availability.days) are replaced as a whole, so read them first with get_whatsapp_ai_rules to add or remove one entry. Decision order for each inbound message: availability schedule → participant list → thread ownership → trigger phrases → aiRule. Does NOT change what the agent says (use update_agent / patch_agent_prompt) and does NOT pause a number (use update_whatsapp_number_settings aiPaused). The response carries warnings when the saved combination would keep the AI silent — relay them to the user.

Change the AI behaviour of ONE WhatsApp number assigned to a Convocore agent (get phoneId from get_whatsapp_ai_rules). Partial update: send only the fields to change. Use aiPaused to stop/resume all AI replies on the number, and coexistenceSettings for numbers shared with the WhatsApp Business app. Does not connect, reassign or remove numbers, and never touches Meta credentials. For reply conditions (phrases, AI rule, schedule, allow/deny list) use update_whatsapp_ai_rules.

Check which channels are connected to an agent: WhatsApp numbers and Facebook pages (Messenger, plus Instagram when an Instagram account is linked to the page). Use it to answer "is my WhatsApp / Instagram connected?" and to confirm a connection after the user finished a connect link. Credentials are never returned. For WhatsApp reply rules use get_whatsapp_ai_rules.

Create a private link the USER opens to connect WhatsApp, Messenger or Instagram to an agent. Connecting needs the user to log in with Meta in their own browser, so you cannot do it for them: create the link, show the returned url to the user as a clickable link, and tell them to come back and say when they are done. The page needs no Convocore login and expires (default 30 minutes). When the user says they finished, call get_agent_channels to confirm the channel is really connected before saying it works. messenger and instagram use the same page: the user picks a Facebook page; Instagram is connected when an Instagram account is linked to that page. whatsappConnectionMode: metaCloudApi (default, a number used only by the AI) or metaCoexistence (a number already used in the WhatsApp Business app, shared with the AI).

Check a connect link created with create_channel_connect_link: pending (not opened), opened / redeemed (the user is on the page), connected, error or expired. To verify the channel itself use get_agent_channels.

Disconnect a Facebook page from an agent: the agent stops answering Messenger and Instagram for that page. pageId comes from get_agent_channels. Confirm with the user first. To connect a page use create_channel_connect_link.

Read outbound call campaigns of an agent. Actions: list (paginated, with progress counters: totalLeads, contactedLeads, successfulCalls, missingCalls, onGoingCalls), get (one campaign by campaignId). To change campaigns use campaigns_write. WhatsApp broadcast campaigns are not covered.

Create, edit, delete, start/stop or restart an outbound call campaign. Actions: create (campaign needs name + leadGroupName; created stopped unless enabled is true), update (partial: send only the fields to change in campaign), delete, enable (START dialing — places real phone calls to the lead group; resumes where it stopped), disable (stop), restart (start again from the first lead; resetConversations=true also clears earlier call conversations). Campaign fields: name, leadGroupName (a lead group name, or "all"), delayBetweenEachCall (seconds), concurrentSlots, initialPrompt, overrideInitialPrompt, postCallPrompt, postCallMetrics (custom metric ids), openTime / closeTime ("HH:mm" 24h), openDays (monday…sunday), timezone (IANA). The agent needs an assigned phone number before a campaign can start.

Read voice call logs of the workspace (web, inbound and outbound calls). Actions: list (filter by agent, type, phone numbers, date range, search; paginated), get (one call by callLogId — transcript and latency data only with mode="full"), export (JSON or CSV of many calls; includeTranscripts=true to add transcripts). Chat conversations are in list_conversations, not here.

Create, edit or delete a call log record. Actions: create (callLog needs agent_id, type web|inbound|outbound, start_time ISO, agent_phone_number and customer_phone_number — null for web calls), update (callLogId + callLog with only the fields to change; agent_id and start_time cannot change), delete (callLogId; permanent). This edits records only — to place a call use start_outbound_call.

Get the phone number(s) assigned to an agent for voice calls. Check this before start_outbound_call — an agent without a number cannot call.

Place a REAL outbound phone call now: the agent calls the "to" number from its assigned number and talks to whoever answers. Bills voice minutes. Confirm the number with the user first. For many leads at once use contact_leads or a campaign (campaigns_write).

Send a REAL SMS from the agent's connected SMS number. sendMode=direct (default) sends message as written; sendMode=agent lets the agent write the text (message is then optional). mediaUrls sends MMS. Bills the workspace. For WhatsApp / Messenger / Instagram replies use send_channel_message instead.

Call or text a LIST of leads in one go (real calls / real SMS, billed). channel=call queues an outbound call to each lead; channel=sms sends each lead a message (message required unless sendMode=agent). leads are lead objects from leads_read (they must carry a phone, e.g. userPhone). Max 500 per call. Confirm the audience with the user first. For scheduled, throttled dialing use a campaign (campaigns_write).

Read the custom analytics metrics of an agent (values the AI extracts from each conversation or call, e.g. customer_satisfaction, booked_meeting). Actions: list, get (metricId), data (aggregated values for one metricKey in a time range: averages/sums for numbers, counts for boolean/enum/string), all_data (same for every metric). Time range defaults to the last 30 days; startTs/endTs are unix seconds. includeTimeSeries adds per-day points.

Create, edit or delete a custom analytics metric on an agent. Actions: create (metric needs key + type + description; type enum also needs options), update (metricId + metric with only the fields to change; changing type can make old data inconsistent), delete (metricId; historical data stays but the metric stops being tracked). Metric: { key, type: number|boolean|enum|string, options?, description? }.

List the lead groups of an agent with the number of leads in each. Groups are what campaigns target (campaign.leadGroupName). Optional tags only counts leads carrying at least one of the tags. To see the leads inside a group use leads_read with groupName.

Create, fill, rename or delete a lead group. Group names are stored lowercase. Actions: create (groupName + leads: new lead objects, e.g. [{ userName, userPhone, userEmail }] — a group exists only while it has leads), assign_leads (groupName + leadIds: move EXISTING leads into the group; groupName "all" removes them from any group), rename (groupName + newGroupName: moves every lead to the new name), delete (groupName: by default the leads are kept and just ungrouped; deleteLeads=true permanently deletes every lead in the group).

Read the agent folders of the workspace (the folders that group agents on the dashboard). Actions: list (all folders with their agentIDs), get (one folder by folderId, or by exact name).

Create, edit or delete agent folders and move agents in or out. Actions: create (folder needs name; optional color, icon, starred, parentFolderID, agentIDs), update (folderId + folder with only the fields to change — use this to rename), delete (folderId; removes the folder only, agents are kept), add_agent / remove_agent (folderId + agentId).

Read the change history of an agent: who changed what and when (newest first). Use it to explain an unexpected behaviour change or find when a setting was edited. Paginate by passing the ts of the last entry as cursorTs.

Re-send the human-handoff notification for a conversation that is waiting for a human (emails the team again). userId is the conversation / end-user id. Sends a real email.

Generate one-paragraph AI summaries for up to 25 conversations, in each conversation language. Simple form: agentId + convoIds (transcripts are loaded for you). Advanced: items [{ convoId, transcript }] with your own text. Returns the summaries only — it does not store them (use update_conversation to save one).

The ready-made agent templates shown in the dashboard gallery. Actions: list (available templates with their templateId), create (templateId, optional title / description: creates a new agent from that template as-is). To build a custom agent for a specific business use create_agent_from_template instead.

Manage an email address subscription to Convocore notification emails. The address owner must confirm with a 6-digit code. Actions: request_code (email: sends the code), verify_code (email + code: returns a token), set_subscription (token + subscribed true/false), unsubscribe (token). You cannot read the code yourself — ask the user for it.

Read details of the WhatsApp numbers connected to an agent. For a quick "is it connected" check use get_agent_channels; for reply rules use get_whatsapp_ai_rules. Actions: list — all numbers of the agent with status, mode and settings | details — live info from Meta: display name, quality rating, messaging limit tier, verification Needs: phoneId. | analytics — WhatsApp conversation and message analytics for the agent | voice_status — re-check with Meta whether WhatsApp voice calling is enabled on the number Needs: phoneId.

Manage a connected WhatsApp number. To CONNECT a new number use create_channel_connect_link (the user must log in with Meta). Confirm with the user before remove. Actions: remove — disconnect the number from the agent (the AI stops answering it) | reassign — move the number to another agent of the workspace Needs: newAgentId. | update_display_name — request a new display name on the WhatsApp business profile Needs: displayName. | set_voice_calling — turn inbound WhatsApp voice calling on or off for the number Needs: enabled.

List the WhatsApp message templates of a number (name, language, category, approval status, components). Templates are required to message a customer outside the 24-hour window and for broadcast campaigns. Actions: list — all templates of the WhatsApp Business account

Create, edit or delete WhatsApp message templates. New and edited templates go to Meta for review before they can be used. Placeholders are {{1}}, {{2}}… in order. Actions: create — submit a new template; give bodyText or components Needs: name, category, language. | update — replace the components (and optionally category) of an existing template Needs: templateId, components. | delete — delete a template by name (all languages unless templateId is given) Needs: name.

List WhatsApp broadcast campaigns of an agent (template messages sent to a lead group) with sent / delivered / failed counts. Outbound CALL campaigns are in campaigns_read. Actions: list — paginated campaigns

Create, edit, delete or send a WhatsApp broadcast campaign: an APPROVED template sent to every lead in a lead group. run sends real WhatsApp messages that Meta bills — always run with dryRun=true first and confirm the audience with the user. Campaign fields: name, leadGroupName (or "all"), phoneId (sending number), templateId, templateName, templateLanguage, templateCategory, variableMapping / headerVariableMapping (how lead fields fill {{1}}, {{2}}…), delayBetweenMessages (seconds, default 2), openTime / closeTime ("HH:mm"), timezone. Actions: create — create a campaign (stopped until run) Needs: campaign. | update — change fields of a campaign Needs: campaignId, campaign. | delete — delete a campaign Needs: campaignId. | run — send the campaign now (dryRun=true to preview) Needs: campaignId.

Diagnose a connected Facebook page (Messenger / Instagram). To list connected pages use get_agent_channels; to connect one use create_channel_connect_link. Actions: check_subscriptions — which webhook events the page is subscribed to — use when the agent does not receive Messenger / Instagram messages Needs: pageId. | get_profile — name and picture of a Messenger / Instagram user who messaged the agent Needs: userId.

Read the SMS numbers of an agent and search numbers that can be rented. Voice phone numbers are in get_agent_phone. Actions: list — SMS numbers connected to the agent Needs: agentId. | analytics — SMS volume and delivery analytics for the agent Needs: agentId. | rental_status — whether the agent has a rented platform number and its state Needs: agentId. | rental_available — whether number rental is offered in a country | search_available — numbers available to rent, filtered by country / area code / digits

Manage the SMS numbers of an agent. Connecting your own Twilio account and paying for a rented number are done on the dashboard (they need credentials / card details that must not go through chat). test_send sends a real SMS. Actions: remove — disconnect an SMS number from the agent Needs: phoneNumber. | assign_rental — attach an already-rented platform number to the agent Needs: phoneNumber. | release_rental — give up the rented number of the agent (it stops working; confirm first) | test_send — send a test SMS from the agent number Needs: testPhoneNumber.

Read the email channel setup of the workspace: sending domains (with the DNS records to add and their verification state), inboxes (addresses agents answer) and recent email events. Actions: domains — sending domains | inboxes — inboxes and their assigned agent | recent_events — recent inbound / outbound email events

Set up and operate the email channel. Flow: create_domain → the user adds the returned DNS records at their DNS provider → verify_domain → create_inbox (address = localPart@domain) assigned to an agent. send_human_reply sends a real email. Actions: create_domain — register a sending domain and get its DNS records Needs: domain. | refresh_domain — re-read the domain status Needs: domainId. | verify_domain — ask for DNS verification after the records were added Needs: domainId. | delete_domain — remove a sending domain (its inboxes stop working) Needs: domainId. | create_inbox — create an address on a verified domain Needs: domainId, localPart. | update_inbox — change display name, assigned agent, active flag or settings Needs: inboxId. | delete_inbox — delete an inbox Needs: inboxId. | send_human_reply — reply to an email conversation as a human, from the inbox Needs: inboxId, reply.

See every integration of the workspace exactly like the dashboard Integrations page: Google Calendar, Outlook Calendar, Google Sheets, Airtable, Shopify, Calendly, Zoho CRM, Gmail, Outlook mail, Zoho Mail and Google Drive. Start with all_connections (every connection id, account, and which agents use it), then agent_integrations to see and debug what one agent has configured (it lists problems such as a missing calendar, a deleted connection or an inbox whose notifications stopped). resources lists what can be picked for an agent: calendars (google_calendar / outlook_calendar), spreadsheet tabs + header columns (google_sheets, pass sheetId), Airtable bases then tables + fields (pass baseId), Calendly event types, Zoho CRM modules, Shopify store check. A first connection (OAuth login) is always made by the user on the dashboard Integrations page; everything after that is done with integrations_write and integrations_test. Actions: all_connections — every connection of every integration, with the agents using each | agent_integrations — one agent's integrations, settings and detected problems Needs: agentId. | resources — calendars / sheet tabs + headers / Airtable bases, tables, fields / Calendly event types / Zoho modules / Shopify check Needs: type. | calendly_event_types — Calendly event types that can be offered by agents | outlook_connections — connected Outlook accounts | outlook_calendars — calendars of a connected Outlook account Needs: connectionId. | zoho_connections — connected Zoho CRM accounts | zoho_modules — Zoho modules (Leads, Contacts, Deals…) Needs: connectionId. | zoho_fields — fields of a Zoho module Needs: connectionId, moduleApiName. | zoho_agent_config — how an agent syncs with Zoho (lookup and field mapping) Needs: agentId. | zoho_assigned_agents — agents that use Zoho CRM

Add, change or remove an integration on an agent, exactly like the dashboard. assign_to_agent also updates an existing setup (call it again with new settings); remove_from_agent removes it. settings by type — google_calendar / outlook_calendar: { connectionId, calendarId, calendarName?, timezone? ("Europe/London" or "GMT+1"), label?, description?, methods? (create-event, check-availability, lookup-events, update-event, delete-event), bookingMode? ("route" = caller picks one calendar, "union" = any free calendar), defaultCallerTimezone? ("" = same as calendar, "ask", or a zone), disableMeetLink? (google, in-person) } — up to 5 calendars per agent; remove one with { calendarId } or all with {}. google_sheets: { connectionId, sheetId, sheetTabName, method: "read" | "lookup" | "write", sheetName?, sheetDescription?, headerRowIndex?, headerDescriptions? {column: meaning}, identifierColumn?, identityFields? { phone, email, name, custom, customLabel } } — up to 5 sheets; remove one with { sheetId }. airtable: { connectionId, baseId, tableId?, method?, fieldDescriptions?, identifierField? }. shopify: { connectionId }. calendly: { connectionId }. zoho_crm: { config } (draft it with zoho_auto_configure; config.logTranscript keeps a note with the real messages, including human replies from WhatsApp/dashboard). gmail / outlook_mail / zoho_mail (the agent answers that inbox): { connectionId, whenToReply? (always | keywords | sentiment | manual), replyDelayMinutes?, replyRule?, humanNotifyRule?, replyLength? (short | medium | long | auto), replyTone?, keywords?, ignoreKeywords?, humanTakeoverEnabled?, humanTakeoverTimeoutMinutes?, notifyWorkspaceOwners? } — also starts inbound notifications. Get ids from integrations_read (all_connections, resources). After assigning, verify with integrations_read agent_integrations and integrations_test. Actions: assign_to_agent — add or update an integration on an agent Needs: agentId, type, settings. | remove_from_agent — remove an integration (or one calendar / sheet / inbox) from an agent Needs: agentId, type. | calendly_save_event_types — choose which Calendly event types agents may offer Needs: connectionId, selectedEventTypes. | calendly_assign_agents — give agents the Calendly booking ability Needs: connectionId, agentIds. | calendly_remove_agent — remove Calendly from an agent Needs: agentId. | google_calendar_disconnect — disconnect a Google Calendar account (confirm first; refused while agents use it unless force) Needs: connectionId. | outlook_disconnect — disconnect an Outlook account (confirm first) Needs: connectionId. | zoho_disconnect — disconnect a Zoho account (confirm first) Needs: connectionId. | zoho_auto_configure — let AI draft a Zoho sync config from the CRM fields (does not save) Needs: connectionId. | zoho_test_lookup — try a config against the CRM with a phone / email, without saving Needs: config. | zoho_save_agent_config — save the Zoho sync config on an agent Needs: agentId, config. | zoho_remove_agent — remove Zoho CRM from an agent Needs: agentId.

Test an agent's integration tools with the agent's REAL runtime code and settings. inspect (no side effects): the exact tool names, descriptions and parameters the agent sees for that integration — use it to debug why the agent misuses a tool. run: executes one of those tools with the given args, exactly as if the agent called it, and returns its output or error. Safe checks first: google-calendar / outlook-calendar check-availability or lookup-events, google-sheets read / lookup, airtable read, shopify read, calendly list_event_types / check_availability. create / update / delete events, sheet writes and Airtable creates really happen — confirm with the user before running those. Actions: inspect — what the agent sees for this integration (names, descriptions, parameters) | run — run one tool with args, as the agent would

Brand the caller's own whitelabel agency (client portal + login page), like the dashboard Agency settings. Never another agency; whitelabel clients cannot use it. get: current branding, login page and domain status (secrets and provider keys are never returned). update_branding { branding }: only the fields sent change — name, logoUrl (round avatar), darkLogoUrl, wideLogoUrl, wideLogoDarkUrl, faviconUrl, brandingText (markdown), primaryColorHex (#RRGGBB, builds the whole palette), themeType (light | dark), themeVariant (default | bordered | flat | faded), themeColorUsage (gradient | colorful | plain), googleFontStack (Google Fonts families in fallback order, e.g. ["Rubik","Almarai"] = Rubik for Latin/digits, Almarai for Arabic), googleFontWeights (default [400,500,700]), customCSS, defaultLanguage (e.g. "ar" — also sets right-to-left), allowedLanguages, mainWebsite, supportEmail, tosPage, privacyPolicyPage, enableClientSignup, disablePasswordLogin. All URLs must be https. update_login_page { loginPage }: merges into the login page — layout (centered | split), mediaSide (start | end: logical, start = left in LTR / right in RTL), mediaUrl, mediaFit (cover | contain), headline (≤120), subtext (≤300), textPlacement (overlay | below), background { type: theme | color | gradient | image, color, from, to, angle 0-360, imageUrl }, card { style: elevated | bordered | flat | glass, radius: sm | md | lg }, mobileMedia (stack | hide), logo (square | wide | none). Split layout without mediaUrl shows a gradient from the primary colour. reset: true clears it. upload_asset { kind, sourceUrl | base64 }: copies an image onto the Convocore CDN and returns its URL (then pass it to update_branding / update_login_page). kinds: logo, dark_logo, wide_logo, wide_logo_dark (≤1 MB png/jpg/webp/svg), favicon (≤256 KB png/ico/svg), login_media, login_background (≤2 MB webp/png/jpg/svg). Custom domains are claimed and verified on the dashboard only. Confirm the brand values with the user before changing a live portal. Actions: get — current branding, login page and domain status | update_branding — change logos, colour, fonts, language, CSS, links, signup/login options Needs: branding. | update_login_page — customise the client login page (layout, media, text, background, card) | upload_asset — put a logo / favicon / login image on the CDN and get its URL Needs: kind.

Browse and search records in the connected Zoho CRM: leads, contacts, deals, accounts or any custom module. list pages through a module (perPage up to 200; pass info.nextPageToken as pageToken past 2000 records). search uses Zoho criteria, e.g. "(Lead_Status:equals:New)" or "((Lead_Source:equals:Chat)and(Created_Time:greater_than:2026-10-01T00:00:00+00:00))"; operators: equals, not_equal, starts_with, in, greater_than, less_than, between. query runs COQL for anything else, e.g. "select Last_Name, Email, Lead_Status from Leads where Lead_Status = 'New' order by Created_Time desc limit 200" (a where clause is required; limit max 2000, use "limit 200, 200" to page). Use integrations_read zoho_fields for the field API names and picklist values. Actions: list — one page of records of a module, newest first if sortBy=Created_Time sortOrder=desc Needs: moduleApiName. | search — records matching criteria / word / email / phone Needs: moduleApiName. | query — COQL SELECT for filters, sorting and counts search cannot do Needs: query. | get — one full record Needs: moduleApiName, recordId.

Create, update, upsert or delete records in the connected Zoho CRM (leads, contacts, deals, accounts, custom modules), up to 100 per call, and add notes. Records use Zoho field API names, e.g. { "Last_Name": "Smith", "Email": "a@b.com", "Lead_Status": "New" }; picklist values must match exactly (integrations_read zoho_fields). The result has one entry per record (success, id, or the Zoho error code and field), so partial failures are visible. delete moves records to the Zoho recycle bin; confirm with the user before deleting or bulk-updating. Actions: create — create records Needs: records. | update — update records by id (only the fields given change) Needs: records. | upsert — insert or update by duplicateCheckFields; each result says insert or update Needs: records. | delete — delete records (confirm first) Needs: recordIds. | add_note — attach a note to a record Needs: recordId, title, content.

Read contacts (identities): one person recognised across channels (WhatsApp, Instagram, web chat, calls…). A contact groups that person's conversations. Different from leads_read (the CRM lead list). Actions: list — contacts of the agent, with search | get — one contact profile with its channels and consent Needs: identityId. | timeline — every conversation of the contact across channels, in order Needs: identityId. | audit_log — merge / unmerge / consent history of the contact Needs: identityId.

Merge, split, update consent of, or delete a contact. merge and delete cannot be undone automatically — confirm with the user. Actions: merge — merge two contacts that are the same person Needs: sourceIdentityId, targetIdentityId. | unmerge — split conversations out of a contact Needs: identityId, convoIds. | set_consent — record the contact marketing consent Needs: identityId, consentStatus. | delete — delete the contact record Needs: identityId.

Read the backups and prompt history of an agent. Check here before a risky change, or to find a version to go back to. Actions: list — saved backups (id, date, author) | latest — the most recent backup | prompt_history — prompt-assistant history with the prompt snapshots that can be restored

Back up or roll back an agent. Take a backup (create) BEFORE large edits with update_agent. restore and revert_prompt overwrite the current agent — confirm with the user and create a backup first. Actions: create — save a backup of the agent as it is now | restore — replace the agent with a saved backup Needs: backupId. | revert_prompt — put back an earlier version of the prompt only Needs: snapshotId. | set_prompt_caching — turn provider prompt caching on or off (cheaper, faster replies for long prompts) Needs: enabled.

Write, check and run CODE tools: JavaScript that runs inside the agent (no server needed), with declared input and output variables. For tools that call an HTTP API use create_agent_tool. Flow: validate → run with sample inputVars → save. Actions: validate — check syntax and the input/output contract without running Needs: code. | run — run the code once with sample inputs and return outputs / logs / errors Needs: code. | ai_edit — have AI rewrite the code for a request (returns code; does not save) Needs: agentId, code, userRequest. | save — create or update the code tool on the agent Needs: agentId, tool.

Copy a tool to other agents or share one tool across the workspace. A COPY is independent afterwards; a SHARED tool stays one tool used by many agents, so editing it changes all of them. Actions: copy — copy a tool to one agent Needs: toolId, targetAgentId. | copy_to_agents — copy a tool (and its variables) to many agents Needs: toolId, targetAgentIds, tool. | set_access — choose who can use the tool: private, whole workspace, chosen agents or client orgs Needs: toolId, agentId, tool, access. | publish_workspace — publish the tool to every agent of the workspace Needs: toolId, agentId, tool. | make_private — stop sharing: the tool belongs to one agent again Needs: toolId, agentId. | share — share an existing tool with the workspace or an org Needs: toolId, scope. | update_shared — edit a shared tool (affects every agent using it) Needs: toolId, tool. | unassign_shared — remove a shared tool from one agent Needs: toolId, agentId. | delete_shared — delete a shared tool for everyone (confirm first) Needs: toolId.

Draft lead-funnel steps (qualification stages and scoring) from an agent prompt with AI. Returns the suggested steps only — save them with update_agent funnelConfig. Pass the agent prompt text; get it from get_agent if needed. Actions: generate — suggest funnel steps

Read workspace-level data: activity and channel webhook logs (to debug "the bot did not reply"), credit balance and plan quota. Actions: logs — recent logs, filterable | log — one log entry in full Needs: logId. | log_timeline — every step of one inbound message, from webhook to reply Needs: traceId. | credits — credit balance | quota — plan limits and current usage

Change workspace settings: name, photo and team members; form-submission notification emails on/off; the workspace's own AI provider keys. Actions: update_team_profile — change workspace name / photo / team (read the current team on the dashboard first: the list replaces the old one) | set_form_submit_emails — turn the workspace-wide "New form submitted" / rating notification emails on or off (default on); per-agent override is vg_uiEngineFormNotifyConfig.enabled Needs: formSubmitEmailsEnabled. | set_provider_keys — store the workspace own AI provider API keys. Keys typed in chat pass through this conversation: prefer the dashboard, and never repeat a key back Needs: keys.

Read usage, credits and activity — everything the dashboard Usage and Analytics pages show — for the whole workspace and per agent. Read only. Time range: days back from now (default 30, max 400) or an explicit from / to (ISO date like 2026-10-01, or a full ISO datetime). overview: ONE call with credit balance, plan quota and limits, credits consumed in the range, tokens per model, the top agents (with names) and total activity (conversations, messages, calls, call minutes) — start here for "how is my usage". top_agents: agents ranked by credits consumed, with share of the total (topN up to 15). credits: current credit balance. quota: plan limits and current usage (conversations, messages, agents, KB…). workspace_usage: the Usage page — creditsCharged and creditsConsumed, input/output tokens per model, credits per agent with per-agent models, plus the chart list; add includeCharts for the chart data and includeLogs or logsPage for the credit usage log (what charged how much, and why). agent_usage (agentId): credits and tokens per model for one agent, plus call minutes. agent_analytics (agentId): that agent's analytics — loads, conversations, metrics, token usage, containment and human-handover stats. agents_analytics: activity totals for all agents (or agentIds), and per agent with includePerAgent (default true). clients_analytics: agency only — usage, leads and funnel per whitelabel client and per agent (clientIds to narrow). email_analytics (agentId): email channel analytics for one agent. WhatsApp and SMS analytics are in whatsapp_numbers_read / sms_numbers_read, voice calls in call_logs_read, knowledge-base quota in get_kb_quota.

Search this MCP server's tool catalog by keyword/domain before calling other tools. Use when unsure which tool to pick among orgs/clients/leads/agent_tools/variables/kb/testing. detail=names|brief|schema. Does not call the Convocore API.