Skip to main content
Glama

Create voice campaign

create_voice_campaign
Destructive

Create an AI voice campaign as a DRAFT: it places no call until it is launched. It is outbound and run by the AI agent of an AI phone line (voice_line_id). Give it its contacts in the same call: contact_rows (phone, name, variables the AI agent reads, optional fallback group and order), or contact_ids of existing contacts, or a label/segment audience (audience_type with audience). Send exactly one of them. Phone numbers are checked right away (a bad one refuses the whole call and says which rows); do-not-call numbers and duplicates are flagged afterwards and read in validation_summary. idempotency_key is required: reuse the same one when you retry, so no second campaign is made. The answer has the campaign id, which every other voice campaign tool takes, and contacts_import. Consent is not part of creating: it is attested when launching.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "title": "<title>",
      "voice_line_id": "<voice_line_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "create_voice_campaign"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleYes
ends_atNoWhen the campaign ends, in the future and after scheduled_at: YYYY-MM-DDTHH:MM in the campaign timezone, or with an offset. Past it the campaign completes, whatever is left to call. An empty string clears it.
audienceNoWith audience_type label: {label_ids: [ids]}; with segment: {custom_filter_id: id}. The contacts are taken when the campaign launches.
timezoneNoIANA name, for example America/Bogota.
ai_settingsNoWhat the AI agent does in this campaign: opening (text per locale es/en), first_speaker (agent or caller), dispositions, extraction_fields, voicemail, hot_lead, ringing_seconds (15 to 60), variable_map. Read get_voice_campaign for the shape in use.
contact_idsNoIds of this account's contacts (their phone number is the one called), at most 2000.
descriptionNo
dialer_modeNoHow fast contacts are dialed (progressive by default); power currently places one call per available agent.
contact_rowsNoThe people to call, at most 2000. Their phone numbers stay in this account; send each person once.
max_attemptsNoCalls to one contact before giving up.
scheduled_atNoWhen to start, in the future: YYYY-MM-DDTHH:MM in the campaign timezone, or with an offset. Launching a campaign that has one schedules it instead of starting it.
audience_typeNoOnly with audience, instead of contact_rows and contact_ids.
voice_line_idYesThe AI phone line that calls (its agent talks, its number shows).
calling_windowNoThe hours and days the campaign may call, in its timezone.
idempotency_keyYesAny unique text you make up for this request. Sending the same one again returns the campaign already created instead of making a second.
retry_delay_minsNoMinutes before the next attempt.
retry_after_voicemailNoCall again after a voicemail (true by default). False ends the contact on a detected voicemail.
target_concurrency_limitNoCalls at the same time.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / ends_at
      Added value: +{
      +  "description": "When the campaign ends, in the future and after scheduled_at: YYYY-MM-DDTHH:MM in the campaign timezone, or with an offset. Past it the campaign completes, whatever is left to call. An empty string clears it.",
      +  "type": "string"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / dialer_mode / description
      Previous value: -"How fast contacts are dialed (progressive by default)."New value: +"How fast contacts are dialed (progressive by default); power currently places one call per available agent."
    • addedInput schema / properties / retry_after_voicemail
      Added value: +{
      +  "description": "Call again after a voicemail (true by default). False ends the contact on a detected voicemail.",
      +  "type": "boolean"
      +}
  3. Added

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior the annotations do not carry: no calls are placed until launch, phone validation happens synchronously and 'a bad one refuses the whole call and says which rows,' while do-not-call and duplicate hits surface later in validation_summary, and the response contains the campaign id plus contacts_import. It also explains retry semantics for idempotency_key, which softens the conservative idempotentHint=false annotation by making idempotency conditional on key reuse rather than contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the draft state, then contact modes, then validation and idempotency behavior — a sensible priority order with no filler sentences. It is a dense single block though, and the long parenthetical about contact_rows fields makes it harder to scan than necessary when the schema already documents those fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with nested objects and no output schema, the description covers the risky parts: no side effects on create, contact-supply exclusivity, validation timing, idempotency, and what the response returns. Remaining gaps are minor configuration parameters (timezone, calling_window, retry settings, dialer_mode) that the schema documents adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 89%, so the baseline is 3, but the description adds a real cross-parameter constraint the schema cannot express (exactly one of contact_rows / contact_ids / audience), plus the meaning of the returned campaign id and validation_summary. It does not touch scheduling, calling_window, or dialer_mode semantics, which remain schema-only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create an AI voice campaign') plus its resulting state ('as a DRAFT: it places no call until it is launched'), which immediately separates it from launch_voice_campaign and the other voice campaign siblings. It also pins down that campaigns are outbound and driven by the agent of a voice_line_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use context (create now, calls only after launching; consent is attested at launch, not here) and an explicit mutual-exclusion rule for the three contact-supply options: contact_rows, contact_ids, or audience_type + audience, 'Send exactly one of them.' It stops short of naming sibling tools such as add_voice_campaign_contacts or update_voice_campaign as alternatives for post-creation changes, so routing is clear in context but not spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources