---
name: cleartalk
description: Build, test, and operate ClearTalk voice and texting agents through the ClearTalk MCP server. Use when working with ClearTalk agents, campaigns, calls, texts, appointments, or Agent Instructions — especially when creating a new agent or improving one that underperforms.
---

# Working with ClearTalk

ClearTalk places and answers real phone calls and text messages for businesses. You reach it through the ClearTalk MCP server's tools; this skill is the craft that makes those tools produce agents that actually perform.

## The mental model

- **Campaigns** are the rail every call or text runs on: they own the agent, calling hours, and phone numbers.
- **Agents** decide what gets said. Simple agents run on **Agent Instructions** (a system prompt). Sophisticated ones follow a **Pathway** — a versioned conversation flow with steps and routing. Texting and chatbot agents are always Pathway-driven.
- **Results** classify how each conversation ended. Reports, webhooks, and follow-up automation all key off them.
- **Credits** are real money. Calls, texts, and simulated test runs all spend them.

## The workflow that works: build → test → read → refine

Never judge an agent by how its instructions read. Judge it by scored test transcripts.

1. **Write the Agent Instructions** (see [references/agent-instructions.md](references/agent-instructions.md) — the craft guide). Create with `create_agent`, refine with `update_agent`.
2. **Build the test suite** for its Pathway: `create_test_scenario` per situation, unhappy paths first — angry, confused, voicemail, wrong person, "how did you get this number". Mark must-pass scenarios `isRequiredForPromotion`. Seed realistic ones from real calls with `generate_test_scenario_from_call`.
3. **Run and read**: `run_all_tests`, then `get_test_run` on failures. Read the transcript like a call reviewer, not a grader: find the exact turn where it went wrong. [references/testing-guide.md](references/testing-guide.md) covers scenario design and score reading.
4. **Refine and re-run** until `get_promotion_readiness` is clean. Only then suggest going live — and the first live call goes to the user's own number via `trigger_call`.

## Safety rules (non-negotiable)

- Tools marked **LIVE OPERATION** ring real phones and spend real money. Confirm with the user before every single one — no standing approvals.
- `check_do_not_contact` before any outreach; any match means no contact.
- Someone asks to be left alone → `add_to_do_not_contact` immediately.
- Bulk outreach (starting campaigns, batch dialing) is deliberately impossible through this server. Don't improvise it by looping `trigger_call`; send the user to the ClearTalk dashboard.

## Where things live

| Need | Tool(s) |
| --- | --- |
| What agents exist / read one | `list_agents`, `get_agent` |
| Build or improve an agent | `create_agent`, `update_agent`, `list_voices` |
| Give an agent facts | `create_knowledge_base`, `list_knowledge_bases` |
| Conversation flows | `list_pathways`, `generate_pathway`, `get_pathway_generation` |
| Test before going live | `create_test_scenario`, `run_test`, `run_all_tests`, `get_test_run`, `get_promotion_readiness` |
| People | `search_contacts`, `get_contact`, `create_contact`, `update_contact` |
| What happened on a call/text | `list_conversations`, `get_conversation` |
| One real call / text | `trigger_call` ⚠, `send_text` ⚠ |
| Appointments | `list_event_types`, `get_available_slots`, `book_appointment` ⚠, `list_bookings` |
| Compliance | `check_do_not_contact`, `add_to_do_not_contact`, `pause_campaign` |