Made in 10Docs
GuidesAPI
MCP server

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

ToolWhat it does
list_charactersYour characters: id, name, role, language, face, voice, greeting
get_characterOne character in full: instructions, greeting, knowledge, language, face, voice, the longest call, and what's attached to it
create_characterA character from scratch. Only name is required; a role without instructions starts from that role's template
update_characterChanges 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_kitsThe starter kits (query, category)
create_character_from_kitA kit's character with the kit's rules attached; optionally another name, face, voice or language
list_facesOur faces (gender)
list_voicesOur voices and your cloned ones (language, gender), and the languages a character may speak

Knowledge, rules and pronunciations

ToolWhat it does
add_knowledgeA 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_knowledgeYour documents without their text (query, tag, status)
attach_knowledgeWhich documents a character uses (mode: add, the default, or replace)
set_guardrailsRules 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_pronunciationsHow its voice says words and names, in one named dictionary (dictionary_name); entries: [] detaches it

Website deployments

ToolWhat it does
list_deploymentsYour 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_deploymentA 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_deploymentIts 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_snippetThe tag with pk_live_…ab12 where the key goes (the key isn't kept), and the header lines
get_widget_textsThe widget's words, per language
set_widget_textsOne 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_looktheme, 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

ToolWhat it does
list_callsCalls, newest first (limit, before)
get_callOne call with its transcript, why it ended, tools used, recording and analysis
get_analyticsCalls, minutes, charges and success rate (days, group_by: day, character or deployment)
list_webhooksYour webhook endpoints, never their secrets
create_webhookAn endpoint; its signing secret is shown only this once
test_webhookSends 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), plus invalid_arguments, confirmation_required, document_failed (a web page we couldn't read; the document is kept with the reason) and unknown_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:

ResourceWhat it is
acme://guide/website-widgetPutting 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/charactersWriting a good character: instructions, greeting, knowledge, guardrails and pronunciations, and their limits
acme://catalog/languagesThe language codes a character's language takes (JSON)

Prompts

PromptArgumentsWhat it walks through
set_up_website_receptionistsite, 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_widgetdeployment_id, languageReads 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:

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.

On this page