> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Create, list, view and change agents.

## How creating an agent works

The three create tools start a build and answer at once with a `build_id`. The build reads the business's website (if given), writes the agent's instructions and greeting, and creates the agent. It takes a minute or two.

The AI app then calls [`get_agent_build_status`](/documentation/mcp/tools/agent-builds#get_agent_build_status) every few seconds until the agent is ready or the build failed.

Every create needs:

* `business_name`, and
* either `website` or a 2–3 sentence `description` of the business.

Everything else is optional. The AI app asks once for the optional details and skips what you don't know.

> [!NOTE]
>
> A build follows the same rules as the agent builder in the VoiceAIWrapper app: your plan, your credits and the daily build limit. Voices are chosen in the VoiceAIWrapper app.

***

## create\_inbound\_receptionist

Create an AI receptionist that answers phone calls for a business. It greets callers, answers questions about the business and handles the jobs you choose, such as taking a message or collecting caller details.

**Scope:** `agents.write` · **Hints:** open world

### Inputs

**business\_name** `string` *required*

The business's name.

**website** `string`

The business's own website, for example `lakesidedental.com`. Required unless you give `description`.

**description** `string`

2–3 sentences on what the business does. Required without a `website`.

**industry** `string`

For example `Healthcare & Medical` or `Home services`.

**opening\_hours** `string`

For example `Mon-Fri 8am-5pm`.

**jobs** `string[]`

What it does on a call, for example `answer questions`, `take messages`, `collect details`.

**collect** `string[]`

Details to collect from callers, for example `name`, `reason for calling`.

**never\_say** `string[]`

Things the agent must never say.

**language** `string`

The language it speaks, by name or code, for example `English` or `es`.

**agent\_name** `string`

The agent's name. A default is used if you skip it.

**tone** `string`

For example `friendly`, `calm`, `professional`.

**request\_id** `string`

Your own id for this request, up to 128 characters. Repeat it on retries so the agent is never built twice. See [Repeating a request safely](/documentation/mcp/tools/overview.md#repeating-a-request-safely).

### Returns

**build\_id** `string`

Pass it to `get_agent_build_status`.

**status** `string`

Always `building`.

```json Example theme={null}
{
  "build_id": "VmF3TmF0aXZlQWdlbnRCdWlsZFR5cGU6YWJjMTIz",
  "status": "building"
}
```

***

## create\_outbound\_agent

Create an AI agent that places phone calls for a business, for example to follow up on leads or confirm appointments. The person called speaks first.

Calls are started from a **campaign** in the VoiceAIWrapper app. The agent has no calling number of its own: the campaign picks the number it calls from.

**Scope:** `agents.write` · **Hints:** open world

### Inputs

Takes everything [`create_inbound_receptionist`](#create_inbound_receptionist) takes, plus:

**call\_goal** `string` *required*

What the calls are for, for example `remind patients of check-ups`.

**who\_is\_called** `string`

Who it calls, for example `new leads`.

**success** `string`

What counts as a successful call, for example `appointment booked`.

For an outbound agent, `jobs` means anything else it does on a call, and `collect` means details to find out on the call.

### Returns

Same as `create_inbound_receptionist`: a `build_id` and `status: "building"`.

***

## create\_website\_chatbot

Create an AI chatbot for a website: an agent that talks with visitors by chat or voice and answers questions about the business, plus the web widget that puts it on the site. When the build is ready, `get_agent_build_status` returns the embed code.

To add a widget to an agent that already exists, use [`create_web_widget`](/documentation/mcp/tools/web-widgets#create_web_widget) instead.

**Scope:** `agents.write` · **Hints:** open world

### Inputs

Same as [`create_inbound_receptionist`](#create_inbound_receptionist). Here `jobs` and `collect` refer to conversations with site visitors.

### Returns

Same as `create_inbound_receptionist`: a `build_id` and `status: "building"`.

***

## list\_agents

List the organization's agents, newest first.

**Scope:** `agents.read` · **Hints:** read-only

### Inputs

None.

### Returns

**agents** `object[]`

**agent**

**agent\_id** `string`

The id other tools take.

**name** `string`

**type** `string`

`answers calls` or `makes calls`.

**has\_number** `boolean`

A phone number is connected.

**has\_widget** `boolean`

It has a web widget.

**link** `string`

The agent's page in the VoiceAIWrapper app.

```json Example theme={null}
{
  "agents": [
    {
      "agent_id": "VmF3TmF0aXZlQWdlbnRUeXBlOng3azJt",
      "name": "Lakeside Dental Receptionist",
      "type": "answers calls",
      "has_number": true,
      "has_widget": false,
      "link": "https://dashboard.voiceaiwrapper.app/en/.../agent/VmF3TmF0aXZlQWdlbnRUeXBlOng3azJt"
    }
  ]
}
```

***

## get\_agent

Show one agent: name, type, greeting, language, the start of its instructions, its phone number and its widget embed code.

**Scope:** `agents.read` · **Hints:** read-only

### Inputs

**agent\_id** `string` *required*

The `agent_id` from `list_agents`.

### Returns

Everything `list_agents` returns for the agent, plus:

**greeting** `string`

What it says first. Empty for none.

**language** `string`

For example `English`, or `Auto-detect`.

**instructions\_summary** `string`

The first 300 or so characters of its instructions.

**phone\_number** `string | null`

The connected number, if any.

**embed\_code** `string | null`

The widget's embed code, if it has a widget.

***

## update\_agent

Change an agent's name, greeting, instructions or language. Give only what changes. The same checks as the VoiceAIWrapper app apply.

The change applies to the live agent straight away, and there is no undo from the chat, so the AI app asks you to confirm first. Voices are changed in the VoiceAIWrapper app.

**Scope:** `agents.write` · **Hints:** destructive

### Inputs

**agent\_id** `string` *required*

The `agent_id` from `list_agents`.

**name** `string`

The new name. Can't be empty.

**greeting** `string`

What it says first. Send an empty string for no greeting.

**instructions** `string`

Its full new instructions. This replaces the old instructions entirely.

**language** `string`

By name or code, for example `English`, `Spanish`, `es`, or `auto` to detect the caller's language.

At least one of `name`, `greeting`, `instructions` or `language` is required.

### Returns

**agent\_id** `string`

**name** `string`

**changed** `string[]`

What changed: any of `name`, `greeting`, `instructions`, `language`. Empty if the agent already had those settings.

**link** `string`

The agent's page in the VoiceAIWrapper app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.