> ## 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`, `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. |
## 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.