Capabilities - PolyAI Platform

Builder MCP exposes PolyAI’s platform as MCP tools, grouped into the families below. Your client discovers them automatically on connection — you don’t configure tools by hand. Each tool carries its own input schema, which the client reads directly from the server; the parameter tables below reproduce that schema so you can see what each tool takes without connecting first. US, UK, and EU workspaces expose 106 tools; self-serve Studio workspaces expose 100 (the Alerts family is enterprise-only). Tool names appear exactly as your client sees them in tools/list.

Every tool maps to a PolyAI REST endpoint. Parameters are named path_*, query_*, or nested under a request body in the raw schema — the tables below strip those prefixes and expand the body’s top-level fields. For deeply nested request bodies, follow the API reference link on each tool for the complete schema. To see exactly what your client discovered, ask it to list its tools or query the endpoint’s tools/list method (see Quickstart → Verify).

Build & manage agents

Agents

`create-agent`

Create agent. API reference: Create agent.

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.
`name`	string	1–100 characters. Required.
`experimentalConfig`	object	Nested object — see the API reference for the full schema.
`responseSettings`	object	Nested object — see the API reference for the full schema. Required.
`llmSettings`	object	Nested object — see the API reference for the full schema.
`voiceSettings`	object	Nested object — see the API reference for the full schema.
`agentId`	string	—

`list-agents`

List agents. API reference: List agents.

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.

`duplicate-agent`

Duplicate agent. API reference: Duplicate agent.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`newAgentName`	string	1–100 characters. Required.
`newAgentId`	string	—

`delete-agent`

Delete agent. API reference: Delete agent.

Parameter	Type	Description
`agentId`	string	The agent. Required.

Behavior

`get-agent-behavior-rules`

Get agent behavior rules. API reference: Get agent behavior rules.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`update-agent-behavior-rules`

Update agent behavior rules. API reference: Update agent behavior rules.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`behavior`	string	— Required.

Branches

`create-branch`

Create branch. API reference: Create branch.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchName`	string	1–100 characters. Required.

`list-branches`

List branches. API reference: List branches.

Parameter	Type	Description
`agentId`	string	The agent. Required.

`delete-branch`

Delete branch. API reference: Delete branch.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`merge-branch`

Merge branch. API reference: Merge branch.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`conflictResolutions`	array	Array.
`deploymentMessage`	string	Default “.

`sync-branch-with-parent`

Sync branch with parent. API reference: Sync branch with parent.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`conflictResolutions`	array	Array.

`deploy-a-branch`

Deploy a branch. API reference: Deploy a branch.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

Deployments

`publish-the-current-draft-to-an-environment`

Publish the current draft to an environment. API reference: Publish the current draft to an environment.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`environment`	string	Environment to publish to (defaults to sandbox).
`deploymentMessage`	string	Message describing this publish. Default “.

`promote-a-deployment-to-the-next-environment`

Promote a deployment to the next environment. API reference: Promote a deployment to the next environment.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`deploymentId`	string	The deployment. Required.
`deploymentMessage`	string	Default “.
`targetEnvironment`	string	One of `pre-release`, `live`.

`rollback-to-a-previous-deployment`

Rollback to a previous deployment. API reference: Rollback to a previous deployment.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`deploymentId`	string	The deployment. Required.
`deploymentMessage`	string	Default “.

`list-deployments-for-an-environment`

List deployments for an environment. API reference: List deployments for an environment.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`environment`	string	Environment to list deployments for (sandbox, pre-release, live). One of `sandbox`, `pre-release`, `live`. Required.
`limit`	integer	Max number of deployments to return.

`get-active-deployment-per-environment`

Get active deployment per environment. API reference: Get active deployment per environment.

Parameter	Type	Description
`agentId`	string	The agent. Required.

Knowledge base

`create-knowledge-base-topic`

Create knowledge base topic. API reference: Create knowledge base topic.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`name`	string	— Required.
`content`	string	— Required.
`actions`	string	—
`isActive`	boolean	—
`exampleQueries`	object	Nested object — see the API reference for the full schema.

`get-knowledge-base-topic`

Get knowledge base topic. API reference: Get knowledge base topic.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`topicId`	string	The knowledge base topic. Required.
`branchId`	string	The branch. Required.

`list-knowledge-base-topics`

List knowledge base topics. API reference: List knowledge base topics.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`update-knowledge-base-topic`

Update knowledge base topic. API reference: Update knowledge base topic.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`topicId`	string	The knowledge base topic. Required.
`agentId`	string	The agent. Required.
`content`	string	—
`name`	string	—
`actions`	string	—
`isActive`	boolean	—
`exampleQueries`	object	Nested object — see the API reference for the full schema.

`delete-knowledge-base-topic`

Delete knowledge base topic. API reference: Delete knowledge base topic.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`topicId`	string	The knowledge base topic. Required.
`branchId`	string	The branch. Required.

Variants

`create-variant`

Create variant. API reference: Create variant.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`name`	string	— Required.
`attributeValues`	object	Default `{'values': {}}`.
`isDefault`	boolean	—

`list-variants`

List variants. API reference: List variants.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`update-variant`

Update variant. API reference: Update variant.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`variantId`	string	The variant. Required.
`agentId`	string	The agent. Required.
`name`	string	—
`attributeValues`	object	Nested object — see the API reference for the full schema.
`isDefault`	boolean	—

`delete-variant`

Delete variant. API reference: Delete variant.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`variantId`	string	The variant. Required.
`branchId`	string	The branch. Required.

Attributes

`create-attribute`

Create attribute. API reference: Create attribute.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`name`	string	— Required.

`list-attributes`

List attributes. API reference: List attributes.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`update-attribute`

Update attribute. API reference: Update attribute.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`attributeId`	string	The attribute. Required.
`agentId`	string	The agent. Required.
`name`	string	— Required.

`delete-attribute`

Delete attribute. API reference: Delete attribute.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`attributeId`	string	The attribute. Required.
`branchId`	string	The branch. Required.

Connectors

`get-a-connector-by-id`

Get a connector by ID. API reference: Get a connector by ID.

Parameter	Type	Description
`connectorId`	string	The connector. Required.
`agentId`	string	The agent. Required.

`batch-get-connectors-by-id`

Batch get connectors by ID. API reference: Batch get connectors by ID.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`connectorIds`	array	List of connector IDs to retrieve. Required.

`list-all-connectors-for-a-project`

List all connectors for a project. API reference: List all connectors for a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.

`update-a-connector`

Update a connector. API reference: Update a connector.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`connectorId`	string	The connector. Required.
`voiceName`	string	Google TTS voice name (e.g. en-US-Neural2-A). tts_lang_code is auto-derived from the voice name prefix. Validated via TTS probe.
`variantId`	string	Variant ID to assign, or null to unassign.
`projectId`	string	Move connector to a different project. API key must have access to both projects.
`asrLangCode`	string	ASR language code (e.g. en-US).

`batch-update-connectors`

Batch update connectors. API reference: Batch update connectors.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`updates`	array	List of connector updates. Required.

`delete-a-connector-and-its-phone-numbers`

Delete a connector and its phone numbers. API reference: Delete a connector and its phone numbers.

Parameter	Type	Description
`connectorId`	string	The connector. Required.
`agentId`	string	The agent. Required.

`look-up-connector-by-phone-number`

Look up connector by phone number. API reference: Look up connector by phone number.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumber`	string	Phone number to look up (E.164 format). Required.

Phone numbers

`get-a-specific-phone-number`

Get a specific phone number. API reference: Get a specific phone number.

Parameter	Type	Description
`phoneNumber`	string	The phone number (E.164). Required.
`agentId`	string	The agent. Required.

`batch-get-phone-numbers`

Batch get phone numbers. API reference: Batch get phone numbers.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumbers`	array	List of phone numbers to retrieve. Required.

`list-all-phone-numbers-for-a-project`

List all phone numbers for a project. API reference: List all phone numbers for a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`connectorId`	string	Filter by connector ID.

`import-a-single-phone-number`

Import a single phone number. API reference: Import a single phone number.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumber`	string	The phone number (E.164). Required.
`clientEnv`	string	Client environment (sandbox, pre-release, live). Default `live`.

`import-phone-numbers-into-a-project`

Import phone numbers into a project. API reference: Import phone numbers into a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumbers`	array	List of phone numbers to import. Required.
`clientEnv`	string	Client environment (sandbox, pre-release, live). Default `live`.

`delete-a-single-phone-number`

Delete a single phone number. API reference: Delete a single phone number.

Parameter	Type	Description
`phoneNumber`	string	The phone number (E.164). Required.
`agentId`	string	The agent. Required.

`delete-phone-numbers-from-a-project`

Delete phone numbers from a project. API reference: Delete phone numbers from a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumbers`	array	List of phone numbers to delete. Required.

`reassign-a-phone-number-to-a-different-connector`

Reassign a phone number to a different connector. API reference: Reassign a phone number to a different connector.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`phoneNumber`	string	The phone number (E.164). Required.
`connectorId`	string	Target connector ID to reassign the phone number to. Required.

Config pages (real-time config)

`get-a-config-page-by-environment`

Get a config page by environment. API reference: Get a config page by environment.

Parameter	Type	Description
`clientEnv`	string	The client environment. Required.
`agentId`	string	The agent. Required.

`list-all-config-pages`

List all config pages. API reference: List all config pages.

Parameter	Type	Description
`agentId`	string	The agent. Required.

`update-config-variables-for-an-environment`

Update config variables for an environment. API reference: Update config variables for an environment.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`clientEnv`	string	The client environment. Required.
`variables`	object	Key-value pairs to merge into the existing config. Required.

`upsert-the-json-schema-for-a-config-page`

Upsert the JSON Schema for a config page. API reference: Upsert the JSON Schema for a config page.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`clientEnv`	string	The client environment. Required.
`schema`	object	JSON Schema (Draft 7) definition. Required.

Functions

`start-function`

Start function. API reference: Start function.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`end-function-`

End function. API reference: End function..

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`execute-a-function`

Execute a function. API reference: Execute a function.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.
`functionId`	string	Path parameter. Required.
`flowId`	string	—
`args`	object	Default `{}`.

`duplicate-a-function`

Duplicate a function. API reference: Duplicate a function.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.
`functionId`	string	Path parameter. Required.
`name`	string	—

`replace-the-start-function-code-`

Replace the start function code. API reference: Replace the start function code..

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`code`	string	— Required.

`replace-the-end-function-code-`

Replace the end function code. API reference: Replace the end function code..

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`code`	string	— Required.

`get-python-type-stubs-for-a-function-`

Get Python type stubs for a function. API reference: Get Python type stubs for a function..

Parameter	Type	Description
`functionId`	string	Path parameter. Required.
`agentId`	string	The agent. Required.

Voice & audio

Voice library

`register-a-new-voice-in-the-voice-library`

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.
`voiceMetadata`	object	Additional voice metadata.
`name`	string	Human-readable voice name. Required.
`providerVoiceId`	string	Voice ID from the TTS provider. Required.
`provider`	string	TTS provider (e.g. GOOGLE, OPENAI, ELEVENLABS). Required.
`config`	object	Provider-specific voice config. Required.

`update-a-voice-in-the-voice-library`

Update a voice in the voice library. API reference: Update a voice in the voice library.

Parameter	Type	Description
`voiceId`	string	The voice. Required.
`accountId`	string	The account (workspace). Required.
`voiceMetadata`	object	Additional voice metadata.
`name`	string	Human-readable voice name.
`providerVoiceId`	string	Voice ID from the TTS provider.
`provider`	string	TTS provider.
`config`	object	Provider-specific voice config.

`get-a-single-voice-from-the-voice-library`

Get a single voice from the voice library. API reference: Get a single voice from the voice library.

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.
`voiceId`	string	The voice. Required.

`list-all-voices-in-the-account-s-voice-library`

List all voices in the account’s voice library. API reference: List all voices in the account’s voice library.

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.
`gender`	string	Filter by voice metadata gender. One of `male`, `female`, `neutral`.
`provider`	string	Filter by TTS provider, e.g. ‘GOOGLE’, ‘ELEVENLABS’.
`language`	string	Filter by voice metadata language, e.g. ‘en-US’.
`isPolyVoice`	boolean	If set, restrict to (or exclude) Poly’s curated voices.

`synthesize-a-short-audio-sample-of-a-voice`

Synthesize a short audio sample of a voice. API reference: Synthesize a short audio sample of a voice.

Parameter	Type	Description
`accountId`	string	The account (workspace). Required.
`voiceId`	string	The voice. Required.

`set-the-project-s-active-voice`

Set the project’s active voice. API reference: Set the project’s active voice.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`voiceId`	string	Voice ID to set as the project voice. Required.

Deployed voice configs

`create-or-update-a-deployed-voice-configuration`

Create or update a deployed voice configuration. API reference: Create or update a deployed voice configuration.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`voiceId`	string	Voice ID to deploy. Required.
`id`	string	Deployed voice ID — omit to create, provide to update.
`probability`	number	Traffic weight (0.0–1.0). Required.

`list-deployed-voice-configurations`

List deployed voice configurations. API reference: List deployed voice configurations.

Parameter	Type	Description
`agentId`	string	The agent. Required.

`delete-a-deployed-voice-configuration`

Delete a deployed voice configuration. API reference: Delete a deployed voice configuration.

Parameter	Type	Description
`deployedVoiceId`	string	The deployed voice configuration. Required.
`agentId`	string	The agent. Required.

Voice & disclaimer tuning

`get-voice-tuning-settings`

Get voice tuning settings. API reference: Get voice tuning settings.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`voiceId`	string	The voice. Required.
`purpose`	string	Tuning purpose filter, e.g. ‘disclaimer’.

`update-voice-tuning-settings`

Update voice tuning settings. API reference: Update voice tuning settings.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`voiceId`	string	The voice. Required.
`resetToDefault`	boolean	Reset settings to provider defaults.
`similarityBoost`	integer	Similarity boost (0–100).
`modelId`	string	Provider model ID override.
`speed`	number	Playback speed multiplier.
`stability`	integer	Voice stability (0–100).

`get-disclaimer-voice-tuning-settings`

Get disclaimer voice tuning settings. API reference: Get disclaimer voice tuning settings.

Parameter	Type	Description
`voiceId`	string	The voice. Required.
`agentId`	string	The agent. Required.

`update-disclaimer-voice-tuning-settings`

Update disclaimer voice tuning settings. API reference: Update disclaimer voice tuning settings.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`voiceId`	string	The voice. Required.
`resetToDefault`	boolean	Reset settings to provider defaults.
`similarityBoost`	integer	Similarity boost (0–100).
`modelId`	string	Provider model ID override.
`speed`	number	Playback speed multiplier.
`stability`	integer	Voice stability (0–100).

Audio cache

`list-audio-cache-entries`

List audio cache entries. API reference: List audio cache entries.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`sort`	string	Sort expression, e.g. “hit_count:desc”, “duration:asc”.
`offset`	integer	Pagination offset. Min 0. Default `0`.
`limit`	integer	Max entries to return (1-200). 1–200. Default `50`.

`delete-audio-cache-entry`

Delete audio cache entry. API reference: Delete audio cache entry.

Parameter	Type	Description
`entryId`	string	The audio cache entry. Required.
`agentId`	string	The agent. Required.

`bulk-delete-audio-cache-entries`

Bulk delete audio cache entries. API reference: Bulk delete audio cache entries.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`ids`	array	List of audio cache entry IDs to delete (max 20). 1–20 items. Required.

`download-cached-audio-file`

Download cached audio file. API reference: Download cached audio file.

Parameter	Type	Description
`entryId`	string	The audio cache entry. Required.
`agentId`	string	The agent. Required.

`replace-audio-file-for-a-cache-entry`

Replace audio file for a cache entry. API reference: Replace audio file for a cache entry.

Parameter	Type	Description
`entryId`	string	The audio cache entry. Required.
`agentId`	string	The agent. Required.

`update-cache-entry-file-and-settings`

Update cache entry file and settings. API reference: Update cache entry file and settings.

Parameter	Type	Description
`entryId`	string	The audio cache entry. Required.
`agentId`	string	The agent. Required.

`generate-a-tts-audio-preview`

Generate a TTS audio preview. API reference: Generate a TTS audio preview.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`config`	object	Provider-specific synthesis config. Required.
`language`	string	BCP-47 language tag, e.g. ‘en-US’. Required.
`provider`	string	TTS provider key, e.g. ‘eleven_labs’, ‘cartesia’. Default `eleven_labs`.
`text`	string	Text to synthesize. Required.
`storeOnS3`	boolean	Store audio on S3 and return a presigned URL.

`preview-tts-audio-for-a-cache-entry`

Preview TTS audio for a cache entry. API reference: Preview TTS audio for a cache entry.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`entryId`	string	The audio cache entry. Required.
`config`	string	Voice tuning settings (provider-specific). Required.
`language`	string	BCP-47 language tag, e.g. ‘en-US’.
`text`	string	Text to synthesize. Required.

Run, test & inspect

Debug chat

`create-a-new-debug-chat-session`

Create a new debug chat session. API reference: Create a new debug chat session.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`integrationAttributes`	object	Custom attributes accessible via conv.integration_attributes in project functions.
`variantId`	string	Variant ID to use.
`channel`	string	Channel type (e.g. chat.polyai).
`asrLangCode`	string	ASR language code (e.g. en-US). Defaults to server config.
`conversationId`	string	Custom conversation ID. Auto-generated if omitted.
`ttsLangCode`	string	TTS language code (e.g. en-US). Defaults to server config.
`clientEnv`	string	Client environment (sandbox, pre-release, live). Required.

`send-a-message-to-a-debug-chat-session`

Send a message to a debug chat session. API reference: Send a message to a debug chat session.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`conversationId`	string	The conversation. Required.
`asrLangCode`	string	ASR language code (e.g. en-US). Defaults to server config.
`metadata`	object	User input metadata.
`ttsLangCode`	string	TTS language code (e.g. en-US). Defaults to server config.
`message`	string	User input message. Default “.
`clientEnv`	string	Client environment (sandbox, pre-release, live). Required.

Conversations

`get-a-conversation-by-id`

Get a conversation by ID. API reference: Get a conversation by ID.

Parameter	Type	Description
`conversationId`	string	The conversation. Required.
`agentId`	string	The agent. Required.

`list-conversations-for-a-project`

List conversations for a project. API reference: List conversations for a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`limit`	integer	Max number of conversations to return. Min 1. Default `50`.
`offset`	integer	Number of conversations to skip. Min 0. Default `0`.

`get-audio-recording-for-a-conversation`

Get audio recording for a conversation. API reference: Get audio recording for a conversation.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`conversationId`	string	The conversation. Required.
`redacted`	boolean	Whether to return redacted audio. Default `False`.
`direction`	string	Audio direction: “combined”, “user”, or “agent”. One of `combined`, `user`, `agent`. Default `combined`.

`add-annotations-to-a-conversation`

Add annotations to a conversation. API reference: Add annotations to a conversation.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`conversationId`	string	The conversation. Required.
`annotations`	array	Array. Required.

`upsert-a-note-on-a-conversation`

Upsert a note on a conversation. API reference: Upsert a note on a conversation.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`conversationId`	string	The conversation. Required.
`note`	string	— Required.

Test suites

`trigger-a-test-run`

Trigger a simulation test run. Select test cases explicitly by id, by severity, or by tag via the select field. The legacy flat testCaseIds body is deprecated but still accepted. API reference: Trigger a test run.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`select`	string	— Required.
`branchId`	string	— Required.
`testCaseIds`	string	—

`get-a-test-run-by-id`

Get a test run by ID. API reference: Get a test run by ID.

Parameter	Type	Description
`testRunId`	string	The test run. Required.
`agentId`	string	The agent. Required.

`list-test-runs-for-a-project`

List test runs for a project. API reference: List test runs for a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`offset`	integer	Number of test runs to skip. Min 0. Default `0`.
`testSetId`	string	Filter by test set ID.
`limit`	integer	Max number of test runs to return. Min 1. Default `100`.
`branchId`	string	Filter by branch ID.

`list-test-cases`

List test cases. API reference: List test cases.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`get-test-case`

Get test case. API reference: Get test case.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`testCaseId`	string	The test case. Required.
`branchId`	string	The branch. Required.

`get-test-execution-history-for-a-project`

Get test execution history for a project. API reference: Get test execution history for a project.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`offset`	integer	Number of history entries to skip. Min 0. Default `0`.
`limit`	integer	Max number of history entries to return. Min 1. Default `100`.
`branchId`	string	Filter by branch ID.
`testCaseId`	string	Filter by test case ID.

Outbound calling

`trigger-an-outbound-call`

Trigger an outbound call. API reference: Trigger an outbound call.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`encryption`	string	Telephony encryption mode. Defaults to tls_srtp.
`variantId`	string	Variant ID to use for the call. If omitted, the default connector for the environment is used.
`metadata`	object	Arbitrary key-value metadata passed through to the call. Must be under 26 KB when base64-encoded.
`countryCode`	string	ISO 3166-1 alpha-2 country code for number parsing (e.g. GB). Only needed when to_number lacks a country prefix.
`toNumber`	string	Phone number to dial in E.164 format (e.g. +442012345678). Required.
`environment`	string	Target environment: sandbox, pre-release, or live. Required.

`get-the-status-of-an-outbound-call`

Get the status of an outbound call. API reference: Get the status of an outbound call.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`callSid`	string	The outbound call SID. Required.
`environment`	string	Target environment: sandbox, pre-release, or live. Required.

Manage agent infrastructure

MCP servers on an agent

`add-mcp-server`

Add MCP server. API reference: Add MCP server.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.
`providerId`	string	— Required.
`timeout`	number	0–30.
`auth`	object	Nested object — see the API reference for the full schema.
`url`	string	— Required.

`list-mcp-servers`

List MCP servers. API reference: List MCP servers.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`agentId`	string	The agent. Required.

`connect-mcp-server`

Connect MCP server. API reference: Connect MCP server.

Parameter	Type	Description
`serverId`	string	The MCP server. Required.
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.

`update-mcp-server`

Update MCP server. API reference: Update MCP server.

Parameter	Type	Description
`branchId`	string	The branch. Required.
`serverId`	string	The MCP server. Required.
`agentId`	string	The agent. Required.
`timeout`	number	0–30.
`auth`	object	Nested object — see the API reference for the full schema.
`url`	string	—

`delete-mcp-server`

Delete MCP server. API reference: Delete MCP server.

Parameter	Type	Description
`serverId`	string	The MCP server. Required.
`agentId`	string	The agent. Required.
`branchId`	string	The branch. Required.

Secrets

`create-a-secret`

Create a secret. API reference: Create a secret.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`value`	string	Secret value. Required.
`name`	string	Display name of the secret. Required.
`description`	string	Description of the secret.

`update-a-secret`

Update a secret. API reference: Update a secret.

Parameter	Type	Description
`agentId`	string	The agent. Required.
`secretName`	string	The secret name. Required.
`description`	string	Description of the secret (unchanged if omitted).
`value`	string	New secret value. Required.

`delete-a-secret`

Delete a secret. API reference: Delete a secret.

Parameter	Type	Description
`secretName`	string	The secret name. Required.
`agentId`	string	The agent. Required.

Monitor deployed agents

The Alerts family is enterprise-only — it’s available on US, UK, and EU workspaces, not on self-serve Studio workspaces.

Watch live agents and react to issues. Backed by the Alerts API.

Alerts

Tool	What it does
`create-alert-rule`	Create a new alert rule. The `account_id` is derived from the `X-API-KEY` header.
`get-alert-rule`	Get a specific alert rule by ID.
`list-alert-rules`	List alert rules with optional filters. Query params: `enabled` (filter by enabled status), `metric` (filter by metric type), `project_id` (filter by project ID), `state` (filter by current alert state — `OK`, `ALERT`, `NO_DATA`, or `UNKNOWN`).
`update-alert-rule`	Update an alert rule. Supports partial updates of alert rule attributes.
`delete-alert-rule`	Delete an alert rule and its associated state, including the Datadog monitor.
`get-active-alerts`	Get active alerts (rules currently in `ALERT` state). Optional query params: `project_id` (filter by project ID), `metric` (filter by metric type).

Limiting what a client can do

To narrow what a client can reach, scope the API key itself. Create a least-privilege key limited to the agents and permissions that client needs — for example, a read-only key for a monitoring assistant. The key’s scope governs which calls succeed, so a narrowly scoped key can’t create, delete, or deploy even though the tools are still discovered.

​Build & manage agents

​Agents

​create-agent

​list-agents

​duplicate-agent

​delete-agent

​Behavior

​get-agent-behavior-rules

​update-agent-behavior-rules

​Branches

​create-branch

​list-branches

​delete-branch

​merge-branch

​sync-branch-with-parent

​deploy-a-branch

​Deployments

​publish-the-current-draft-to-an-environment

​promote-a-deployment-to-the-next-environment

​rollback-to-a-previous-deployment

​list-deployments-for-an-environment

​get-active-deployment-per-environment

​Knowledge base

​create-knowledge-base-topic

​get-knowledge-base-topic

​list-knowledge-base-topics

​update-knowledge-base-topic

​delete-knowledge-base-topic

​Variants

​create-variant

​list-variants

​update-variant

​delete-variant

​Attributes

​create-attribute

​list-attributes

​update-attribute

​delete-attribute

​Connectors

​get-a-connector-by-id

​batch-get-connectors-by-id

​list-all-connectors-for-a-project

​update-a-connector

​batch-update-connectors

​delete-a-connector-and-its-phone-numbers

​look-up-connector-by-phone-number

​Phone numbers

​get-a-specific-phone-number

​batch-get-phone-numbers

​list-all-phone-numbers-for-a-project

​import-a-single-phone-number

​import-phone-numbers-into-a-project

​delete-a-single-phone-number

​delete-phone-numbers-from-a-project

​reassign-a-phone-number-to-a-different-connector

​Config pages (real-time config)

​get-a-config-page-by-environment

​list-all-config-pages

​update-config-variables-for-an-environment

​upsert-the-json-schema-for-a-config-page

​Functions

​start-function

​end-function-

​execute-a-function

​duplicate-a-function

​replace-the-start-function-code-

​replace-the-end-function-code-

​get-python-type-stubs-for-a-function-

​Voice & audio

​Voice library

​register-a-new-voice-in-the-voice-library

​update-a-voice-in-the-voice-library

​get-a-single-voice-from-the-voice-library

​list-all-voices-in-the-account-s-voice-library

​synthesize-a-short-audio-sample-of-a-voice

​set-the-project-s-active-voice

​Deployed voice configs

​create-or-update-a-deployed-voice-configuration

​list-deployed-voice-configurations

​delete-a-deployed-voice-configuration

Build & manage agents

Agents

`create-agent`

`list-agents`

`duplicate-agent`

`delete-agent`

Behavior

`get-agent-behavior-rules`

`update-agent-behavior-rules`

Branches

`create-branch`

`list-branches`

`delete-branch`

`merge-branch`

`sync-branch-with-parent`

`deploy-a-branch`

Deployments

`publish-the-current-draft-to-an-environment`

`promote-a-deployment-to-the-next-environment`

`rollback-to-a-previous-deployment`

`list-deployments-for-an-environment`

`get-active-deployment-per-environment`

Knowledge base

`create-knowledge-base-topic`

`get-knowledge-base-topic`

`list-knowledge-base-topics`

`update-knowledge-base-topic`

`delete-knowledge-base-topic`

Variants

`create-variant`

`list-variants`

`update-variant`

`delete-variant`

Attributes

`create-attribute`

`list-attributes`

`update-attribute`

`delete-attribute`

Connectors

`get-a-connector-by-id`

`batch-get-connectors-by-id`

`list-all-connectors-for-a-project`

`update-a-connector`

`batch-update-connectors`

`delete-a-connector-and-its-phone-numbers`

`look-up-connector-by-phone-number`

Phone numbers

`get-a-specific-phone-number`

`batch-get-phone-numbers`

`list-all-phone-numbers-for-a-project`

`import-a-single-phone-number`

`import-phone-numbers-into-a-project`

`delete-a-single-phone-number`

`delete-phone-numbers-from-a-project`

`reassign-a-phone-number-to-a-different-connector`

Config pages (real-time config)

`get-a-config-page-by-environment`

`list-all-config-pages`

`update-config-variables-for-an-environment`

`upsert-the-json-schema-for-a-config-page`

Functions

`start-function`

`end-function-`

`execute-a-function`

`duplicate-a-function`

`replace-the-start-function-code-`

`replace-the-end-function-code-`

`get-python-type-stubs-for-a-function-`

Voice & audio

Voice library

`register-a-new-voice-in-the-voice-library`

`update-a-voice-in-the-voice-library`

`get-a-single-voice-from-the-voice-library`

`list-all-voices-in-the-account-s-voice-library`

`synthesize-a-short-audio-sample-of-a-voice`

`set-the-project-s-active-voice`

Deployed voice configs

`create-or-update-a-deployed-voice-configuration`

`list-deployed-voice-configurations`

`delete-a-deployed-voice-configuration`