> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools Reference
> Complete reference for every tool exposed by the Tavus MCP server, grouped by category.
The Tavus MCP server exposes the full agentic PAL toolkit to MCP clients. Each tool maps to a Tavus API operation and is callable from any MCP-aware client (for example, Codex or Claude Code). This page is a complete reference of every tool, grouped by category.
For installation and authentication, see the [MCP server](/sections/agent-tools/mcp-server) page. For the equivalent command-line surface, see the [CLI](/sections/agent-tools/cli). For the autonomous PAL loop, see [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify).
Tools are first-class objects, not inlined on the PAL. Before giving a PAL a tool, check the saved library with `tavus_tool_list` or `tavus_describe_pal_options`, then either attach an existing tool (`tavus_pal_tools_attach`) or create a new one (`tavus_tool_create`) and attach it. Writing tools inline via `tavus_patch_pal` (`layers.*.tools`) is deprecated. When you create a tool that overlaps an existing one, the response carries a `_tool_reuse_advisory` so you can reuse instead.
MCP tools return data plus optional file manifests for the client to handle. They never write files to disk themselves.
## PAL CRUD & patch
| Tool | Parameters | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_list` | `limit=25`, `page=0`, `pal_type=None` | List PALs with an optional type filter. |
| `tavus_pal_get` | `pal_id`, `include_settings=False` | Fetch a single PAL by ID; optionally include settings. |
| `tavus_pal_create` | `system_prompt=None`, `pal_name="Agentic Tavus PAL"`, `default_face_id=None`, `pipeline_mode="full"`, `greeting=None`, `context=None`, `layers=None`, `memories=None`, `objectives_id=None`, `guardrails_id=None`, `guardrail_ids=None`, `guardrail_tags=None`, `document_ids=None`, `document_tags=None`, `is_template=None` | Create a PAL. `system_prompt` is required for `pipeline_mode="full"`. Tools are attached separately after creation. |
| `tavus_pal_delete` | `pal_id` | Delete a PAL by ID. |
| `tavus_patch_pal` | `pal_id`, `ops` | Patch a PAL with JSON Patch operations. Ops that write inline tools (`layers.*.tools`) return `_inline_tools_deprecated` steering you to the attach/create flow. |
| `tavus_describe_pal_options` | `pal_id` | Describe one PAL plus the account resources (guardrails, objectives, documents, tools, voices) that can be attached to it. |
`pipeline_mode` is one of `full` (LLM + TTS + STT + perception), `speech-to-speech` (no LLM), or `echo` (TTS + transport only).
## Face
| Tool | Parameters | Description |
| ----------------- | ------------------------- | ------------------------------------------------------------------ |
| `tavus_face_list` | `limit=25`, `stock=False` | List faces; when `stock=True`, filters to system/stock faces only. |
## Conversation
| Tool | Parameters | Description |
| --------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `tavus_conversation_create` | `pal_id=None`, `face_id=None`, `conversation_name=None` | Create a conversation with an optional PAL and face. Returns the conversation object with id and URL. |
| `tavus_conversation_end` | `conversation_id` | End a conversation by ID. |
## Quickstart
| Tool | Parameters | Description |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_quickstart` | `system_prompt`, `pal_name="Agentic Tavus PAL"`, `face_id=None` | One-shot recipe: create a PAL, pick a stock face when needed, and create a conversation. Returns the PAL plus the conversation. |
## Templates
| Tool | Parameters | Description |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_from_template` | `template`, `pal_name=None`, `business_context=None`, `default_face_id=None`, `layers=None` | Create a PAL from a built-in prompt template (customer-support, interviewer, sales, tutor, dev-rel) with optional business context and layer overrides. |
## Scaffold
| Tool | Parameters | Description |
| ---------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `tavus_scaffold_embed` | `conversation_url`, `target="iframe"`, `component_name="TavusConversation"` | Return starter files for embedding a Tavus conversation URL. `target` is one of `iframe`, `cvi-ui`, `vanilla`. |
## Resource list
| Tool | Parameters | Description |
| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_resource_list` | `resource`, `limit=25` | List account resources. `resource` is one of `guardrails`, `objectives`, `documents`, `voices`, `skills`, `tools` (singular aliases accepted). |
## Guardrails
Guardrails use a flat, per-rule shape by default (not legacy sets).
| Tool | Parameters | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_guardrail_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `tags=None`, `legacy=False`, `verbose=False` | List guardrails with optional filtering. `type` is one of `user`, `system`, `all`. `verbose` adds `persona_refs` and `guardrail_type`. |
| `tavus_guardrail_get` | `guardrail_id`, `verbose=False`, `legacy=None` | Fetch a single guardrail. |
| `tavus_guardrail_create` | `guardrail_name`, `guardrail_prompt`, `modality="verbal"`, `callback_url=""`, `tool_call=None`, `app_message=True`, `tags=None` | Create a flat guardrail with optional callback and tool-call payload. `modality` is one of `verbal`, `visual`, `audio`. |
| `tavus_guardrail_patch` | `guardrail_id`, `guardrail_name=None`, `guardrail_prompt=None`, `modality=None`, `callback_url=None`, `tool_call=None`, `app_message=None`, `tags=None` | Update a guardrail. Omit fields to leave them unchanged; each supplied field is replaced whole. |
| `tavus_guardrail_delete` | `guardrail_id` | Delete a guardrail by ID. |
| `tavus_guardrail_tags` | `search=None`, `page=None`, `limit=None` | List tags applied to the account's guardrails. |
## Objectives
Objectives are stored as sets; PALs reference a set by `objectives_id`.
| Tool | Parameters | Description |
| -------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_objective_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `sort="ascending"` | List objective sets. `type` is one of `user`, `system`, `all`. |
| `tavus_objective_get` | `objectives_id` | Fetch a single objective set. |
| `tavus_objective_create` | `data`, `name=""`, `allow_loops=False` | Create an objective set. Each item has `objective_name` (letters/digits/underscores only), `objective_prompt`, optional `confirmation_mode` ("auto"\|"manual"), `modality` ("verbal"\|"visual"\|"audio"), `output_variables`, `callback_url`, `tool_call`, and chains via `next_required_objective` or `next_conditional_objectives` (not both). When `allow_loops=False`, exactly one item must be root. |
| `tavus_objective_patch` | `objectives_id`, `ops` | Patch an objective set with JSON Patch ops; cycle and single-root validation re-runs. |
| `tavus_objective_delete` | `objectives_id` | Delete an objective set by ID. |
| `tavus_objective_validate` | `data`, `name=""`, `allow_loops=False` | Validate an objective-set payload (cycles, single root, references) without persisting. |
## Tools (PAL tool library)
| Tool | Parameters | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tavus_tool_list` | `limit=25`, `page=1`, `type="user"`, `name_or_uuid=None`, `sort="ascending"` | List tools. `type` filters by ownership (`user`, `system`, `all`). |
| `tavus_tool_get` | `tool_id` | Fetch a single tool by ID. |
| `tavus_tool_create` | `name`, `description`, `parameters=None`, `delivery=None`, `origin="llm"`, `on_call=None`, `on_resolve="fire_and_forget"`, `static_filler=None` | Create a tool. Placeholders `{ident}` in url/body/query must be declared in `parameters.properties`. Description plus parameters JSON must total ≤ 10,000 chars. Returns `_tool_reuse_advisory` if similar tools exist. For [post-call actions](/sections/conversational-video-interface/pal/post-call-tool), use the CLI `tool create --file` or Tools API with `trigger_type: "post_call"` (not yet a parameter on this MCP tool). |
| `tavus_tool_patch` | `tool_id`, `name=None`, `description=None`, `parameters=None`, `delivery=None`, `origin=None`, `on_call=None`, `on_resolve=None`, `static_filler=None` | Update a tool. Omit fields to leave them unchanged. Secrets returned scrubbed (`********`) from a prior GET must be omitted, not re-sent. |
| `tavus_tool_delete` | `tool_id` | Delete a tool by ID. |
`delivery` defaults to `{"app_message": true}` (Daily data channel), or use `{"api": {...}}` for HTTPS calls with headers, query params, body template, content type, timeout (default 10s, max 60s), and auth (`none`, `bearer`, `basic`, `api_key`, `hmac`, `oauth2_client_credentials`).
## Pronunciation dictionaries
Pronunciation dictionaries are referenced from PALs via `layers.tts.pronunciation_dictionary_id`.
| Tool | Parameters | Description |
| --------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pronunciation_dictionary_list` | `limit=25`, `page=0`, `sort="desc"` | List pronunciation dictionaries. |
| `tavus_pronunciation_dictionary_get` | `dictionary_id` | Fetch a single pronunciation dictionary. |
| `tavus_pronunciation_dictionary_create` | `name`, `rules=None` | Create a dictionary. Each rule is `{text, pronunciation, type: "alias"\|"ipa", alphabet?, case_sensitive?, word_boundaries?}`; max 10,000 rules. Text values must be unique. |
| `tavus_pronunciation_dictionary_patch` | `dictionary_id`, `name=None`, `rules=None` | Update a dictionary. Supplying `rules` replaces the full list (no merge). |
| `tavus_pronunciation_dictionary_delete` | `dictionary_id` | Delete a dictionary by ID. |
## PAL tools (attach & detach)
| Tool | Parameters | Description |
| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_tools_list` | `pal_id` | List tools currently attached to a PAL. |
| `tavus_pal_tools_attach` | `pal_id`, `tool_ids` | Attach one or more existing tools to a PAL by ID. A PAL can hold up to 50 tools. If any attached tool is vision/audio, the PAL's `perception_model` auto-bumps to `raven-1` (response carries `_perception_model_bumped_to_raven_1`). |
| `tavus_pal_tools_detach` | `pal_id`, `tool_id` | Detach a single tool from a PAL. |
## PAL capabilities
The five built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory. Prefer these over raw JSON Patch or raw skills: they accept friendly IDs (`magic_canvas`, `slide_presenter`, `web_search`, `perception`, `memory`, plus the portal IDs `builtin:magic_canvas`, `builtin:slide_presenter`, `builtin:web_search`, `skill:memory`) and know that Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL's skills while Perception persists through `layers.perception`.
| Tool | Parameters | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_capability_catalog` | — | List the five PAL Maker capabilities and their backend mappings. |
| `tavus_pal_capabilities_list` | `pal_id` | List Magic Canvas, Slide Presenter, Web Search, Perception, and Memory attachment state and config for a PAL. |
| `tavus_pal_capability_attach` | `pal_id`, `capability_id`, `config=None`, `document_ids=None`, `slides_trigger=None`, `prompt=None`, `magic_canvas_components=None`, `magic_canvas_usage_guidance=None`, `scheduling_url=None`, `scheduling_provider=None`, `perception_model=None`, `visual_awareness_queries=None`, `audio_awareness_queries=None`, `visual_tool_prompt=None`, `audio_tool_prompt=None` | Attach a capability. Options are capability-specific: Slide Presenter uses `document_ids`/`slides_trigger`/`prompt`; Magic Canvas uses `magic_canvas_*`/`scheduling_*`; Perception uses `perception_model` and the visual/audio awareness fields; Web Search and Memory take no config. |
| `tavus_pal_capability_patch` | same as `tavus_pal_capability_attach` | Update the config of an already-attached capability. |
| `tavus_pal_capability_detach` | `pal_id`, `capability_id` | Detach a capability. Perception detaches by setting `perception_model: off`; the other four detach from `/pals/{id}/skills`. |
## Skills (raw RQH)
Lower-level access to the RQH skill registry and a PAL's raw skill attachments. Use [PAL capabilities](#pal-capabilities) for the five PAL Maker capabilities; reach for these only to work with a skill by its raw registry ID.
| Tool | Parameters | Description |
| ------------------------ | ----------------------------------- | -------------------------------------------------------------------- |
| `tavus_skill_list` | — | List registered RQH skills/capabilities available to attach to PALs. |
| `tavus_pal_skills_list` | `pal_id` | List raw RQH skill attachments for a PAL. |
| `tavus_pal_skill_attach` | `pal_id`, `skill_id`, `config=None` | Attach or replace one raw RQH skill on a PAL. |
| `tavus_pal_skill_patch` | `pal_id`, `skill_id`, `config` | Merge config into an already-attached raw RQH skill. |
| `tavus_pal_skill_detach` | `pal_id`, `skill_id` | Detach one raw RQH skill from a PAL. |
## Knowledge documents
Account-level Knowledge document records that back a PAL's Knowledge section. With a normal Tavus API key, create documents from an already-reachable URL (`tavus_document_create`). Local file upload uses the same portal-only path as PAL Maker and requires a locally running MCP server (to read the file) plus `TAVUS_PORTAL_BEARER_TOKEN`.
| Tool | Parameters | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `tavus_document_list` | `limit=25`, `page=0`, `status=None`, `tags=None`, `participant_tags=None`, `name_or_uuid=None`, `verbose=True` | List Knowledge documents available to attach to PALs. |
| `tavus_document_get` | `document_id`, `verbose=True` | Get one Knowledge document record. |
| `tavus_document_create` | `document_url`, `document_name=None`, `tags=None`, `participant_tags=None`, `crawl=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False` | Create a Knowledge document from an already-hosted URL. |
| `tavus_document_upload` | `local_path`, `document_name=None`, `tags=None`, `participant_tags=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False`, `bucket_name="developer-portal-documents"`, `region="us-east-1"`, `sign_duration=None` | Upload a local file through tavus-api/S3, then create the document record. Requires `TAVUS_PORTAL_BEARER_TOKEN`. |
| `tavus_document_tags` | `search=None`, `page=None`, `limit=None` | List document tags that can be attached to PAL Knowledge. |
| `tavus_document_chunks` | `document_id`, `collection="regular"`, `limit=100`, `offset=None` | Read the extracted chunks RQH indexed for a document. Use before making claims about a document's contents. |
| `tavus_document_recrawl` | `document_id`, `crawl=None` | Trigger a recrawl for a crawl-backed Knowledge document. |
## PAL Knowledge
A PAL's Knowledge section is its `document_ids` plus `document_tags`, with RAG tuning under `layers.knowledge_base`. Create documents first with the [Knowledge documents](#knowledge-documents) tools, then attach them here.
| Tool | Parameters | Description |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_knowledge_list` | `pal_id` | Show Knowledge documents/tags attached to a PAL and resolve the direct document IDs into records. |
| `tavus_pal_knowledge_add` | `pal_id`, `document_ids=None`, `document_tags=None` | Attach existing Knowledge documents or document tags to a PAL. |
| `tavus_pal_knowledge_remove` | `pal_id`, `document_ids=None`, `document_tags=None` | Remove Knowledge documents or document tags from a PAL. |
| `tavus_pal_knowledge_replace` | `pal_id`, `document_ids=None`, `document_tags=None` | Replace the PAL's Knowledge document/tag selections. |
| `tavus_pal_knowledge_settings_patch` | `pal_id`, `rag_score_threshold=None`, `rag_n_chunks=None`, `rag_surrounding_chunk_radius=None`, `enable_rag_observability_app_messages=None`, `use_procedure_goalchain=None` | Patch RAG tuning settings under `layers.knowledge_base`. |
| `tavus_pal_knowledge_upload` | `pal_id`, `local_path`, `document_name=None`, `tags=None`, `participant_tags=None`, `custom_description=None`, `is_customer_support_document=False`, `font_size_aware_extraction=False`, `bucket_name="developer-portal-documents"`, `region="us-east-1"`, `sign_duration=None`, `attach=True` | Upload a local file as a Knowledge document and attach it to the PAL by default. Requires `TAVUS_PORTAL_BEARER_TOKEN`. |
## Builder
The builder is an LLM-guided PAL creation flow.
| Tool | Parameters | Description |
| ---------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tavus_builder_create` | `name`, `greeting=None`, `pal_id=None`, `model=None` | Create a builder session, optionally based on an existing PAL. |
| `tavus_builder_list` | `limit=None`, `page=None`, `pal_id=None`, `name=None`, `status=None` | List builder sessions with optional filters. |
| `tavus_builder_get` | `builder_id` | Fetch a single builder by ID. |
| `tavus_builder_delete` | `builder_id` | Delete a builder session. |
| `tavus_builder_chat` | `builder_id`, `message` | Send a chat turn to the builder. Returns assistant text, autocomplete suggestions, a `draft_ready` flag, and target sections for scoped updates. |
| `tavus_builder_chat_history` | `builder_id`, `limit=50` | Fetch chat history for a builder session. |
| `tavus_builder_append_messages` | `builder_id`, `messages` | Append messages to builder chat history. |
| `tavus_builder_update_objectives` | `builder_id`, `message` | Update objectives based on a user feedback message. |
| `tavus_builder_update_guardrails` | `builder_id`, `message` | Update guardrails based on a user feedback message. |
| `tavus_builder_update_greeting` | `builder_id`, `message` | Update the greeting/opening based on feedback. |
| `tavus_builder_update_personality` | `builder_id`, `message`, `pal_name=False`, `system_prompt=False` | Update PAL personality/system prompt based on feedback. Optionally include PAL name and/or system prompt fields. |
| `tavus_builder_publish` | `builder_id` | Publish the builder's drafted PAL. |
## Chat mode (text-only)
| Tool | Parameters | Description |
| ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `tavus_chat_start` | `pal_id`, `custom_greeting=None`, `conversation_name=None` | Start a text-only conversation with a PAL. Use this to test a built PAL by sending typed turns; no face video is rendered. |
| `tavus_chat_turn` | `conversation_id`, `text`, `timeout_s=20.0` | Send one user turn and wait for the PAL's reply. Returns `{text: }`. |
| `tavus_chat_end` | `conversation_id` | End a chat-mode conversation. |
## PAL preview & build-and-verify
| Tool | Parameters | Description |
| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tavus_pal_preview` | `pal_id`, `face_id=None`, `conversation_name=None` | Start a full audio/video preview conversation against a PAL and return `{conversation_id, conversation_url, ...}`. Hand the URL to a human for visual verification. |
| `tavus_pal_build_and_verify` | `prompt`, `face_id=None`, `max_rounds=4`, `answers=None` | Build a PAL from one creator prompt (optionally using supplied answers for builder follow-ups), then publish and validate via CVI chat mode. When `face_id` is omitted, a default is selected and attached. |
See [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify) for expected agent usage, CLI usage, and how to read the simulated-turn verdict.