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.
list-agents
List agents.
API reference: List agents.
duplicate-agent
Duplicate agent.
API reference: Duplicate agent.
delete-agent
Delete agent.
API reference: Delete agent.
Behavior
get-agent-behavior-rules
Get agent behavior rules.
API reference: Get agent behavior rules.
update-agent-behavior-rules
Update agent behavior rules.
API reference: Update agent behavior rules.
Branches
create-branch
Create branch.
API reference: Create branch.
list-branches
List branches.
API reference: List branches.
delete-branch
Delete branch.
API reference: Delete branch.
merge-branch
Merge branch.
API reference: Merge branch.
sync-branch-with-parent
Pull the latest changes from the branch’s parent (main) into it, without merging the branch back. Use to keep a long-lived branch up to date before merging.
API reference: Sync branch with parent.
deploy-a-branch
Deploy a branch’s current configuration to an environment (sandbox, pre-release, or live). Triggers any configured test runs as part of the deployment.
API reference: Deploy a branch.
check-branch-divergence
Check whether a branch has diverged from its parent branch (the parent has new changes the branch does not have).
API reference: Check branch divergence.
get-merge-history-for-a-branch
Get the merge history for a branch, showing which branches were merged into it and when.
API reference: Get merge history for a branch.
tag-a-branch-as-staging
Tag a branch as staging to deploy it to pre-release. Only direct children of main can be tagged, and one branch holds the staging tag per project.
API reference: Tag a branch as staging.
remove-the-tag-from-a-branch
Remove the tag from a branch, clearing the environment it was deployed to (pre-release for staging, sandbox for internal).
API reference: Remove the tag from a branch.
list-archived-branches
List deleted and merged branches that can be restored within their 30-day retention window. Each entry’s status says whether it was merged or deleted.
API reference: List archived branches.
restore-an-archived-branch
Restore a soft-deleted branch from the archive back to an active state.
API reference: Restore an archived branch.
Deployments
publish-the-current-draft-to-an-environment
Publish the current draft to an environment.
API reference: Publish the current draft to an environment.
promote-a-deployment-to-the-next-environment
Promote a deployment to the next environment.
API reference: Promote a deployment to the next environment.
rollback-to-a-previous-deployment
Rollback to a previous deployment.
API reference: Rollback to a previous deployment.
list-deployments
List deployments for an environment.
API reference: List deployments for an environment.
get-a-deployment
Get a single deployment by ID.
API reference: Get a deployment.
get-active-deployment-per-environment
Get active deployment per environment.
API reference: Get active deployment per environment.
Knowledge base
create-knowledge-base-topic
Create knowledge base topic.
API reference: Create knowledge base topic.
get-knowledge-base-topic
Get knowledge base topic.
API reference: Get knowledge base topic.
list-knowledge-base-topics
List knowledge base topics.
API reference: List knowledge base topics.
update-knowledge-base-topic
Update knowledge base topic.
API reference: Update knowledge base topic.
delete-knowledge-base-topic
Delete knowledge base topic.
API reference: Delete knowledge base topic.
Variants
create-variant
Create variant.
API reference: Create variant.
list-variants
List variants.
API reference: List variants.
update-variant
Update variant.
API reference: Update variant.
delete-variant
Delete variant.
API reference: Delete variant.
Attributes
create-attribute
Create attribute.
API reference: Create attribute.
list-attributes
List attributes.
API reference: List attributes.
update-attribute
Update attribute.
API reference: Update attribute.
delete-attribute
Delete attribute.
API reference: Delete attribute.
Connectors
get-a-connector-by-id
Get a connector by ID.
API reference: Get a connector by ID.
batch-get-connectors-by-id
Batch get connectors by ID.
API reference: Batch get connectors by ID.
list-all-connectors-for-a-project
List all connectors for a project.
API reference: List all connectors for a project.
update-a-connector
Update a connector.
API reference: Update a connector.
batch-update-connectors
Batch update connectors.
API reference: Batch update connectors.
delete-a-connector-and-its-phone-numbers
Delete a connector and its phone numbers.
API reference: Delete a connector and its phone numbers.
look-up-connector-by-phone-number
Look up connector by phone number.
API reference: Look up connector by phone number.
Connector tokens
A connector token is the per-environment credential a telephony or websocket integration presents so PolyAI routes the call to this agent in that environment. It is not an API key. Treat it as a secret.list-connector-tokens
List the connector token for each client environment of an agent. Only environments that already have a connector are returned.
API reference: List connector tokens.
get-the-connector-token-for-an-environment
Get the connector token for one client environment. Returns 404 if the environment has no connector yet.
API reference: Get connector token.
ensure-a-connector-token-exists-for-an-environment
Create a connector for one client environment if none exists, and return its token. Safe to call repeatedly: an existing token is returned unchanged.
API reference: Ensure connector token.
Phone numbers
get-a-specific-phone-number
Get a specific phone number.
API reference: Get a specific phone number.
batch-get-phone-numbers
Batch get phone numbers.
API reference: Batch get phone numbers.
list-all-phone-numbers-for-a-project
List all phone numbers for a project.
API reference: List all phone numbers for a project.
import-a-single-phone-number
Import a single phone number.
API reference: Import a single phone number.
import-phone-numbers-into-a-project
Import phone numbers into a project.
API reference: Import phone numbers into a project.
delete-a-single-phone-number
Delete a single phone number.
API reference: Delete a single phone number.
delete-phone-numbers-from-a-project
Delete phone numbers from a project.
API reference: Delete phone numbers from a project.
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.
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.
list-all-config-pages
List all config pages.
API reference: List all config pages.
update-config-variables-for-an-environment
Update config variables for an environment.
API reference: Update config variables for an environment.
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.
Flows
list-flows
List all flows on a branch.
API reference: List flows.
create-flow
Create a flow on a branch.
API reference: Create flow.
get-flow
Get a single flow by ID.
API reference: Get flow.
update-flow
Update a flow’s name, description, start step, or steps.
API reference: Update flow.
delete-flow
Delete a flow from a branch.
API reference: Delete flow.
Functions
list-all-functions-for-an-agent-on-a-branch
List all functions for an agent on a branch.
API reference: List functions.
create-a-new-function
Create a new custom function on a branch.
API reference: Create function.
get-a-single-function-by-id
Get a single function by ID.
API reference: Get function.
update-a-function
Partially update a function: name, description, code, parameters, or latency control. Renaming also rewrites the def name in the code. Returns 409 Conflict if a rename would orphan flow-step references, unless force is true.
API reference: Update function.
delete-a-function
Archive a function on a branch. Returns 409 Conflict if the function is still referenced by flow steps, topics, stop keywords, behaviors, or variables. Call get-function-references first to see what would break.
API reference: Delete function.
get-function-references
List the entities that reference a function.
API reference: Get function references.
validate-all-functions
Return validation issues found across all functions on a branch.
API reference: Validate functions.
get-the-start-function-code
Get the start function code. Runs synchronously before every conversation greeting.
API reference: Get start function.
get-the-end-function-code
Get the end function code. Runs asynchronously after every conversation ends.
API reference: Get end function.
execute-a-function
Execute a function.
API reference: Execute function.
duplicate-a-function
Duplicate a function.
API reference: Duplicate function.
replace-the-start-function-code
Replace the entire code of the start function. This is a complete replacement, not a partial edit.
API reference: Replace start function.
replace-the-end-function-code
Replace the entire code of the end function. This is a complete replacement, not a partial edit.
API reference: Replace end function.
get-python-type-stubs-for-a-function
Return generic Python type-stub boilerplate (for example, the Conversation class) for IDE autocomplete when editing a function’s code.
API reference: Get function type definitions.
Builder knowledge
Search PolyAI’s builder knowledge base for design patterns, implementation rules, and best practices before building or modifying an agent.search-the-builder-knowledge-base
Search the builder knowledge base. Returns ranked results by relevance.
API reference: Search the builder knowledge base.
list-builder-knowledge-categories
List the available knowledge categories to help narrow searches, such as functions, flows, prompting, entities, deployment, integrations, scopes, and patterns.
API reference: List builder knowledge categories.
This tool takes no parameters.
read-a-builder-knowledge-document-by-path
Read the full content of a knowledge base document by its file path. Use after searching. Returns structured fields parsed from YAML frontmatter plus the markdown body.
API reference: Read a builder knowledge document.
Voice & audio
Voice library
register-a-new-voice-in-the-voice-library
Register a new voice in the voice library.
API reference: Register a new voice in the voice library.
update-a-voice-in-the-voice-library
Update a voice in the voice library.
API reference: Update a voice in the voice library.
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.
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.
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.
set-the-project-s-active-voice
Set the project’s active voice.
API reference: Set the project’s active voice.
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.
list-deployed-voice-configurations
List deployed voice configurations.
API reference: List deployed voice configurations.
delete-a-deployed-voice-configuration
Delete a deployed voice configuration.
API reference: Delete a deployed voice configuration.
Voice & disclaimer tuning
get-voice-tuning-settings
Get voice tuning settings.
API reference: Get voice tuning settings.
update-voice-tuning-settings
Update voice tuning settings.
API reference: Update voice tuning settings.
get-disclaimer-voice-tuning-settings
Get disclaimer voice tuning settings.
API reference: Get disclaimer voice tuning settings.
update-disclaimer-voice-tuning-settings
Update disclaimer voice tuning settings.
API reference: Update disclaimer voice tuning settings.
Audio cache
list-audio-cache-entries
List audio cache entries.
API reference: List audio cache entries.
Filter values take an optional operator prefix:
eq: (default), gt:, ge:, lt:, le:, in:, ex:, contains: or exists:.
delete-audio-cache-entry
Delete audio cache entry.
API reference: Delete audio cache entry.
bulk-delete-audio-cache-entries
Bulk delete audio cache entries.
API reference: Bulk delete audio cache entries.
download-cached-audio-file
Download cached audio file.
API reference: Download cached audio file.
replace-audio-file-for-a-cache-entry
Replace audio file for a cache entry.
API reference: Replace audio file for a cache entry.
update-cache-entry-file-and-settings
Update cache entry file and settings.
API reference: Update cache entry file and settings.
generate-a-tts-audio-preview
Generate a TTS audio preview.
API reference: Generate a TTS audio preview.
preview-tts-audio-for-a-cache-entry
Preview TTS audio for a cache entry.
API reference: Preview TTS audio for a cache entry.
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.
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.
Conversations
get-a-conversation-by-id
Get a conversation by ID.
API reference: Get a conversation by ID.
list-conversations-for-a-project
List conversations for a project.
API reference: List conversations for an agent.
Filter values take an optional operator prefix: eq: (default), gt:, ge:, lt:, le:, in:, ex:, contains: or exists:.
get-audio-recording-for-a-conversation
Get audio recording for a conversation.
API reference: Get audio recording for a conversation.
add-annotations-to-a-conversation
Add annotations to a conversation.
API reference: Add annotations to a conversation.
upsert-a-note-on-a-conversation
Upsert a note on a conversation.
API reference: Upsert a note on a conversation.
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.
get-a-test-run-by-id
Get a test run by ID.
API reference: Get a test run by ID.
list-test-runs-for-a-project
List test runs for a project.
API reference: List test runs for a project.
list-test-cases
List test cases.
API reference: List test cases.
get-test-case
Get test case.
API reference: Get test case.
get-test-execution-history-for-a-project
Get test execution history for a project.
API reference: Get test execution history for a project.
Outbound calling
trigger-an-outbound-call
Trigger an outbound call.
API reference: Trigger an outbound call.
get-the-status-of-an-outbound-call
Get the status of an outbound call.
API reference: Get the status of an outbound call.
Manage agent infrastructure
MCP servers on an agent
add-mcp-server
Add MCP server.
API reference: Add MCP server.
list-mcp-servers
List MCP servers.
API reference: List MCP servers.
connect-mcp-server
Connect MCP server.
API reference: Connect MCP server.
update-mcp-server
Update MCP server.
API reference: Update MCP server.
delete-mcp-server
Delete MCP server.
API reference: Delete MCP server.
Secrets
create-a-secret
Create a secret.
API reference: Create a secret.
update-a-secret
Update a secret.
API reference: Update a secret.
delete-a-secret
Delete a secret.
API reference: Delete a secret.
Monitor deployed agents
The Alerts family is enterprise-only — it’s available on US, UK, and EU workspaces, not on self-serve Studio workspaces.

