Tools, resources and prompts
Everything the MCP server lets an assistant do, what each tool runs, and how it answers and refuses.
Your assistant picks the tools; you just ask. This page is what it can reach, so you know what to ask for. Every tool runs through /v1 with your key, so the API's checks, limits and messages apply.
Tools
Characters
| Tool | What it does |
|---|---|
list_characters | Your characters: id, name, role, language, face, voice, greeting |
get_character | One character in full: instructions, greeting, knowledge, language, face, voice, the longest call, and what's attached to it |
create_character | A character from scratch. Only name is required; a role without instructions starts from that role's template |
update_character | Changes instructions, greeting, knowledge, language, face, voice, tier, the longest call, or recording. Only what's given changes |
delete_character ⚠ | Deletes the character, and takes down every website deployment showing it |
list_starter_kits | The starter kits (query, category) |
create_character_from_kit | A kit's character with the kit's rules attached; optionally another name, face, voice or language |
list_faces | Our faces (gender) |
list_voices | Our voices and your cloned ones (language, gender), and the languages a character may speak |
Knowledge, rules and pronunciations
| Tool | What it does |
|---|---|
add_knowledge | A text, or a public web page, PDF or .docx by its https address, as a document; with character_id it's attached to that character at once |
list_knowledge | Your documents without their text (query, tag, status) |
attach_knowledge | Which documents a character uses (mode: add, the default, or replace) |
set_guardrails | Rules the character never breaks, in one named set attached to it (set_name, by default <name> rules); rules: [] detaches the set. Answers all its sets |
set_pronunciations | How its voice says words and names, in one named dictionary (dictionary_name); entries: [] detaches it |
Website deployments
| Tool | What it does |
|---|---|
list_deployments | Your key's env's deployments, with the character's name, the sites, caps, busy message, the key's last four, and the languages the widget has texts in |
create_deployment | A character on your sites (example.com is taken as https://example.com), with caps, a busy message and a note. Answers the tag with its key (shown once) and the lines a strict site's headers need |
update_deployment | Its name, note, sites, caps or busy message. sites and caps replace all of theirs |
revoke_deployment ⚠ | Takes it down for good |
roll_deployment_key ⚠ | A new key and tag; the old one works for grace_seconds (a day by default, at most a week) |
get_embed_snippet | The tag with pk_live_…ab12 where the key goes (the key isn't kept), and the header lines |
get_widget_texts | The widget's words, per language |
set_widget_texts | One language's teaser_messages (1 to 5, 140 characters each), launcher_label (24), panel_title (40), panel_subtitle (80). "" or [] removes one; other languages and the look stay |
set_widget_look | theme, colors, dark_colors, launcher (style, phone style, corner, offsets, icon), teaser (when, how often, phones, pages) and pages. null resets a part; the texts stay |
Texts and look are live at once: the tag on your site never changes for them. See Appearance for what each part means.
Calls, analytics and webhooks
| Tool | What it does |
|---|---|
list_calls | Calls, newest first (limit, before) |
get_call | One call with its transcript, why it ended, tools used, recording and analysis |
get_analytics | Calls, minutes, charges and success rate (days, group_by: day, character or deployment) |
list_webhooks | Your webhook endpoints, never their secrets |
create_webhook | An endpoint; its signing secret is shown only this once |
test_webhook | Sends a webhook.test event now and says what the endpoint answered |
delete_webhook ⚠ | Deletes an endpoint and its delivery history |
Destructive tools ask first
The tools marked ⚠ do nothing without confirm: true. Without it they answer a confirmation_required error that says what would happen, for example:
This deletes Sophie (chr_…) for good and takes down 1 website deployment(s) showing it. Nothing was changed. Ask the person to confirm, then call this tool again with confirm: true.
So the assistant asks you, and only calls again once you said yes. Tools that only read say so to your client (readOnlyHint); add_knowledge, create_webhook and test_webhook say they reach the web (openWorldHint).
Answers and errors
- An answer is one text, a one-line summary then the JSON, and the same JSON as structured content.
- A refusal is a tool error with the text "message (code)" and
structuredContent.error:{ code, message, status, retry_after_seconds }. The codes are/v1's own (Errors), plusinvalid_arguments,confirmation_required,document_failed(a web page we couldn't read; the document is kept with the reason) andunknown_tool. - Arguments are strict. An argument a tool doesn't take is a tool error naming the ones it does.
Resources
Short guides your assistant can read:
| Resource | What it is |
|---|---|
acme://guide/website-widget | Putting a character on a website: the tag, the sites, the caps, the texts per language and the look, the headers a strict site needs, and what to do when the key is lost |
acme://guide/characters | Writing a good character: instructions, greeting, knowledge, guardrails and pronunciations, and their limits |
acme://catalog/languages | The language codes a character's language takes (JSON) |
Prompts
| Prompt | Arguments | What it walks through |
|---|---|---|
set_up_website_receptionist | site, languages, business (optional) | A receptionist from the kit, the business's facts, the deployment and the tag, and the widget's words in each language |
translate_widget | deployment_id, language | Reads a deployment's widget texts and writes them in another language |
Examples
"Add a Persian receptionist to example.com, greeting in Persian and English." The assistant calls list_starter_kits, then create_character_from_kit with kit_id: "receptionist" and language: "fa". It asks you for the opening hours and adds them with add_knowledge. It calls create_deployment with your sites (example.com and https://www.example.com), and pastes the tag into your site's layout if it can edit it. Then set_widget_texts twice: once in Persian, once in English.
"Our site has a German version now." list_deployments, get_widget_texts, then set_widget_texts with language: "de" and the same words in German. No new tag.
"Make the bubble match our green and put it bottom-left; don't pop up on checkout." One set_widget_look:
{
"deployment_id": "key_…",
"colors": { "accent": "#1f5553" },
"launcher": { "position": "bottom-left" },
"teaser": { "pages": { "hide_on": ["/checkout*"] } }
}"Take the bubble off the site." revoke_deployment answers confirmation_required; the assistant asks you; you say yes; it calls revoke_deployment again with confirm: true.