Skip to main content

​
What is this?

These tools let the assistant create and manage AI agents: build a whole agent in one step, change its instructions, knowledge, skills, settings and capabilities, add your own HTTP and MCP tools, test it with real messages, check it is ready, and publish it. New agents are always created inactive, and publishing only happens when you ask. These tools belong to the Workspace MCP. Each tool below shows its Mode (Read runs immediately; Write asks your MCP client to confirm first) and the Permission needed for it to appear for your key — “None” means every connected key sees it.

​
What can I do here?

  • List and read AI agents, their knowledge, skills and activity
  • Build an agent from a description, or change an existing one
  • Add your own HTTP and MCP tools to an agent
  • Test an agent with messages, check readiness, and publish

​
Tools

​
list_ai_agents

List the AI agents of the user’s current channel: name, type, description, status and tone. Mode: Read · Permission needed: ai:view

​
get_ai_agent

Details of one AI agent (from list_ai_agents): description, status, tone, model provider, its instructions and which capabilities are turned on for it. Mode: Read · Permission needed: ai:view

​
list_ai_settings

The AI models this channel can use (provider, model, text or voice, which one is active). Pick an id for update_agent_settings; an agent without one follows the channel’s active text setting. Never returns API keys. Mode: Read · Permission needed: ai:view

​
create_ai_agent

Create a new AI Agent (draft) in the user’s current channel with a name, optional description, instructions and tone. The agent is created INACTIVE: it does not answer customers until it is published, and it has no knowledge, skills or tools yet. Check list_ai_agents first so you do not duplicate one. Write the instructions from what the user told you about their business; do not invent facts (prices, hours, policies). If the user has not said what the agent should do, ask before proposing. Mode: Write · Permission needed: ai:create

​
build_ai_agent

Build a NEW AI Agent from the user’s description in ONE step (one approval): the agent (created INACTIVE, a draft), its instructions and tone, knowledge (pasted text or web addresses), skills and which capabilities are on. Prefer this over create_ai_agent plus several add_* calls when the user describes a whole agent. Use only what the user told you: if you lack something that matters (what the business does, what the agent may or may not do, where its knowledge lives, who takes over), ask first; never invent prices, hours, policies or web addresses. Handoff recipients are NOT part of this (channel-wide: set_handoff_assignment). It does not publish: afterwards tell the user to test it, then offer check_agent_readiness and publish_ai_agent. Mode: Write · Permission needed: ai:create

​
update_ai_agent

Change an existing AI Agent’s name, description, instructions or tone (agentId from list_ai_agents). Only the fields you give are changed, and systemInstructions REPLACES the whole instructions text: read the current ones with get_ai_agent first (long ones are shown truncated; if so, tell the user and ask before replacing) and send the complete new text. It does not turn the agent on or off, and does not touch its knowledge, skills or tools. Mode: Write · Permission needed: ai:edit

​
add_agent_knowledge

Give an existing AI Agent knowledge to answer from: pasted text the user provided, one web page, a sitemap or an llms.txt. It starts reading in the background (it is NOT ready instantly: say it is processing and that check_agent_readiness shows when it is done). Only use content or addresses the user gave you. Uploaded files cannot be added from here. Mode: Write · Permission needed: ai:create

​
add_agent_skill

Add a skill to an existing AI Agent: a named procedure it looks up when a matching situation comes up (e.g. refund-policy, book-appointment) instead of cramming everything into its main instructions. Base it on what the user told you; do not invent policies. Mode: Write · Permission needed: ai:create

​
set_agent_capability

Turn one of an AI Agent’s capabilities (the actions it may take in a conversation, e.g. handoff_to_human, add_contact_label, close_conversation) on or off, optionally with a guideline for when to use it. Read the agent’s current capabilities with get_ai_agent first and use the exact key shown. Only for that agent; it does not change other agents. Mode: Write · Permission needed: ai:edit

​
set_handoff_assignment

Choose who receives conversations an AI Agent hands over to a human: nobody in particular (shared unassigned queue), one team member, or a group taking turns (round_robin) or the least busy (least_busy). IMPORTANT: this is a setting of the whole channel, shared by every AI Agent on it. Get team members with list_team_members and pass their userIds. Turning handoff on or off for one agent is set_agent_capability with handoff_to_human. Mode: Write · Permission needed: ai:edit

​
check_agent_readiness

Check whether an AI Agent is ready to go live: instructions, knowledge (ready / still processing / failed), skills, enabled capabilities, human handoff and the channel’s AI model setting, plus whether the channel’s AI Agent switch is on. Use it after building or changing an agent and before publish_ai_agent. Report what is missing in plain words. Mode: Read · Permission needed: ai:view

​
list_agent_knowledge

What an AI agent has been taught: each knowledge source with its type, title or address, status (pending, processing, processed, failed), the error if it failed and how much text was read. Use it after add_agent_knowledge to see whether it finished. Never returns the stored text. Mode: Read · Permission needed: ai:view

​
retry_agent_knowledge

Run a knowledge source that failed again (from list_agent_knowledge; only status failed). It processes in the background. Mode: Write · Permission needed: ai:edit

​
list_agent_skills

The skills of an AI agent in full (name, when to use it, the procedure, enabled or not), so you can review or improve them. Mode: Read · Permission needed: ai:view

​
update_agent_skill

Change one skill of an AI agent: rename it, rewrite when to use it or the procedure, or switch it on or off. Only the fields you give change; the procedure text is replaced as a whole. Switching a skill off is how it is retired over MCP; deleting stays in the dashboard. Mode: Write · Permission needed: ai:edit

​
update_agent_settings

Change an AI agent’s settings: its type, which AI model it uses, which channel types it answers on, reply modes, response language, priority, image understanding and guardrails. Only the fields you give change; instructions, knowledge, skills and capabilities are untouched and nothing is published. Over MCP guardrails can be turned on but never off — that is a dashboard action. Mode: Write · Permission needed: ai:edit

​
list_external_capabilities

The channel’s own HTTP and MCP tools (External Capabilities): name, type, server or endpoint, how it signs in and its status (needs_credentials means it was saved without a working login and is off until someone adds it in the dashboard). Give an agent id to see whether that agent has each one on. Credentials are never returned. Mode: Read · Permission needed: ai:view

​
add_external_capability

Give an AI agent one of your own tools: the tools of an MCP server (by URL and tool names) or one call to an HTTP API (method, body, a description for the agent and its inputs), signed in with no auth, a bearer token or OAuth client credentials. The tool is shared by every agent on the channel and switched on for this one. If the MCP server refuses the login, the tools are saved switched off as needs_credentials and you add the login in the dashboard. Credentials are stored encrypted and never shown again. Mode: Write · Permission needed: ai:create

​
get_agent_activity

How an AI agent (or all agents of the channel) has been used lately: tool and skill calls, failures, conversations, and which capabilities and skills were used most. Counts only — no customer text. Mode: Read · Permission needed: ai:view

​
test_ai_agent

Try an AI agent the way a customer would before it goes live: send one message and get its reply, the tools it used and a session to continue the conversation. It runs the real agent against a labelled throwaway test contact, so its tools can act on that contact only, and it uses your AI credits. Works on drafts. Mode: Write · Permission needed: ai:edit

​
publish_ai_agent

Put an AI Agent live so it starts answering real customers. Only when the user explicitly asks to publish or activate, after check_agent_readiness, and never in the same reply that builds the agent: the user should test it first (the dashboard’s Playground). Set enableChannelAgenticMode true only if the user wants the channel’s AI Agent switch turned on too (check_agent_readiness shows it); without that switch on, no agent answers customers. Mode: Write · Permission needed: ai:edit

​
Troubleshooting / Technical Notes

  • A tool I expect isn’t offered. The MCP server only offers tools whose required permission your API key’s owner holds, re-checked on every call. Grant the permission shown on the tool — see Team.
  • A Write tool never seems to run. Your MCP client asks you to approve every Write tool call. Check for a pending approval prompt.
  • A call returns an error. See MCP errors.
Last modified on October 29, 2026