Tough Tongue AI

View saved version →

---
name: getting-started
description: >
  Onboard a user to the ToughTongue AI plugin: verify the MCP connection and
  PAT, look at what's in their account, and route them into their first
  workflow. This skill should be used when the user says "get started with
  ToughTongue", "set up ToughTongue", "is my ToughTongue MCP working",
  "test my ToughTongue connection", "what can I do with ToughTongue", or has
  just installed the plugin. Not for creating, refining, or analyzing
  scenarios directly — hand off to scenario-creator, scenario-refiner, or
  session-analyst for those.
---

# Getting Started with ToughTongue

Verify the setup, orient around the user's account, and launch their first
journey. Keep each step short — this is a welcome mat, not a manual.

## Step 1: Verify the connection

Call the `ttai` MCP tool `list_organizations`.

- **Tools not found** — the MCP server is not registered. Ask how they
  installed:
  - Plugin install: restart the agent app fully and start a new thread; the
    plugin registers the server via its bundled `.mcp.json`.
  - Skills-only install (skills.sh / Cursor): register manually —
    `codex mcp add ttai --url https://api.toughtongueai.com/api/public/mcp
    --bearer-token-env-var TTAI_PAT` (Codex) or
    `claude mcp add --transport http ttai
    https://api.toughtongueai.com/api/public/mcp
    --header "Authorization: Bearer ${TTAI_PAT}"` (Claude Code).
- **401 / auth error** — the PAT is not visible to the agent process. Walk
  through: create a token at <https://app.toughtongueai.com/developer>,
  `export TTAI_PAT="<token>"` in the shell profile, on macOS also
  `launchctl setenv TTAI_PAT "$TTAI_PAT"`, then fully quit and reopen the
  agent app. NEVER ask the user to paste the token into the chat.
- **Success** — report what came back: personal account only, or
  organizations (name them). Explain that org work needs `org_id` passed to
  tools, and this happens automatically in the other skills.

## Step 2: Orient around the account

Call `list_scenarios`, and `list_sessions` with a small limit.

Summarize in 2-3 sentences what exists: how many scenarios, whether sessions
have been run, whether analyses are present. This decides the recommended
first journey below.

## Step 3: Launch the first journey

Offer the paths that fit what Step 2 found, then invoke the matching skill:

| Account state | Recommend | Skill |
|---|---|---|
| Empty (no scenarios) | Create a first practice scenario from a brief, URL, or call transcript | **scenario-creator** |
| Scenarios but few sessions | Share a practice link; or create a scenario for an upcoming meeting | **scenario-creator** |
| Sessions with analyses | Team/scenario performance report | **session-analyst** |
| Low-scoring or complained-about scenario | Diagnose and fix it from real transcripts | **scenario-refiner** |

Close by showing 2-3 of these prompts as things to try next (pick the ones
matching their account state):

- "Pull the last 3 calls from Gong where we lost on pricing and create a
  practice scenario for that objection."
- "For my discovery-call scenario, pull the last 50 sessions — what are the
  top 5 improvement areas?"
- "Pull the 5 lowest-scoring sessions for our onboarding scenario and fix
  the scenario."
- "I have a call with [name] from [company] in 30 minutes — create a quick
  practice scenario so I can rehearse."

View saved version →

---
name: scenario-creator
description: >
  Create ToughTongue AI practice scenarios (cold call, sales roleplay, coaching)
  via the ttai MCP server. Classifies the scenario type, applies type-specific
  authoring rules, gathers context from URLs, transcripts, or other connected
  tools, validates against a checklist, and creates the scenario with
  ttai:create_scenario. Use when the user says "create a scenario", "build a
  practice scenario", "make a roleplay for...", "I have a call in 30 minutes,
  help me rehearse", or provides a brief, company info, or call transcripts
  for scenario creation.
---

# Scenario Creator

Create production-ready ToughTongue AI scenarios and push them live through the
ttai MCP server. Classify → load rules → gather context → draft → validate →
`ttai:create_scenario` → return the practice link.

## Prerequisites

- The **ttai** MCP server must be connected. Tool references below use the
  `ttai:` server prefix (e.g. `ttai:create_scenario`); some agents surface
  these as `mcp__ttai__create_scenario`. If the tools are missing, tell the
  user to install the ToughTongue plugin or add the MCP server (see the repo
  README) with a `TTAI_PAT` token from
  <https://app.toughtongueai.com/developer>.

## Workflow

### Step 1: Establish account context

Call `ttai:list_organizations` first.

- If the user belongs to organizations and the scenario is for a team, pass the
  chosen `org_id` on every subsequent tool call.
- If no organizations, or the scenario is personal practice, omit `org_id`.
- If ambiguous, ask which context to create in.

### Step 2: Classify scenario type

| Type | AI plays | Reference file |
|------|----------|----------------|
| **Cold Call / SDR** | The outbound caller (user plays the lead) | [references/cold-call.md](references/cold-call.md) |
| **Sales Roleplay** | The prospect (user practices selling) | [references/sales-roleplay.md](references/sales-roleplay.md) |
| **Coaching** | The trainer/mentor (teaches via exercises) | [references/coaching.md](references/coaching.md) |
| **Demo** | The AI SDR / product demo agent | [references/demo.md](references/demo.md) |
| **Other** | Anything else (interview, support, negotiation) | [references/scenario-fields.md](references/scenario-fields.md) only |

Decision signals:

- "cold call", "outbound", "lead qualification", "AI calls the customer",
  "SDR call" → Cold Call / SDR
- "practice selling", "objection handling", "prospect roleplay", "pitch practice",
  "prep me for this meeting" → Sales Roleplay
- "coach", "train my team", "teach", "onboarding", "framework" → Coaching
- "demo my product", "AI SDR demo", "show prospects", "browser demo",
  "slide demo", "product walkthrough" → Demo

If ambiguous, ask ONE question: "Should the AI play the caller/seller, the
buyer/prospect, a coach/trainer, or a product demo agent?"

Read [references/scenario-fields.md](references/scenario-fields.md) (always)
plus the matching type reference.

### Step 3: Gather context

- **URLs provided** (company site, product page, LinkedIn): fetch them. Extract
  company name, product, target audience, key features, pricing model. Fold
  into the `ai_instructions` CONTEXT section and `user_friendly_description`.
- **Other connected tools**: if the user references meetings, CRM records, call
  transcripts, or documents available through other MCP servers (calendar,
  Gong, Notion, ...), pull the relevant details and use them as scenario
  context — real names, real objections, real positioning beat invented ones.
- **Pasted material** (transcripts, briefs, positioning docs): mine it for the
  persona, objections, and vocabulary the scenario should reproduce.

### Step 4: Clarifying questions (minimal)

Only ask when the answer is not obvious from the brief. Otherwise use defaults:

| Question | Ask when | Default |
|----------|----------|---------|
| Language & voice | Locale unclear from context | `en-US`, defaults from [references/scenario-fields.md](references/scenario-fields.md) |
| Call sub-type (cold call) | Warm/cold/follow-up unclear | Warm lead |
| Coaching pattern | Coaching type only | Pattern A (Situation-First) |
| Public or private | Team/enterprise use implied | `is_public: true` |

### Step 5: Draft the scenario payload

Build a JSON payload matching the `ttai:create_scenario` input schema (load
the tool schema before calling). Author these fields, in order of importance:

1. `name` — short, descriptive display title.
2. `ai_model_config` — set explicitly based on scenario type. See the "When
   to use which" table in [references/scenario-fields.md](references/scenario-fields.md).
   Cold call and slide-demo scenarios use Landmass/cascade-01 (requires TTS,
   STT, LLM fields). Sales roleplay uses Galaxy/medium. Coaching and
   browser-demo use Ocean/medium-stable.
3. `ai_instructions` — the core field, 500+ words, structured with `##`
   sections per the type reference. For Landmass/cascade scenarios, also load
   [references/cascade-tts.md](references/cascade-tts.md) and include the
   voice-pipeline blocks (output rules, transcription-error handling, natural
   speech style, SSML emotion tags if Cartesia).
4. `user_instructions` — what the human should know before starting:
   situation → what to expect → how to succeed → tips.
5. `rubrik` — evaluation criteria. CRITICAL: evaluate the correct party
   (cold call rubrics evaluate the LEAD; sales rubrics evaluate the REP;
   demo rubrics produce a buyer intelligence report).
6. `user_friendly_description` — 1-2 public-facing sentences.
7. `strategy`, `tools_config`, `session_analysis`, `appearance` — per the
   type reference and [references/scenario-fields.md](references/scenario-fields.md) defaults.
8. `is_recording: true` for voice scenarios; `is_public` per Step 4.

Do NOT set `id` — `ttai:create_scenario` rejects it (that is
`ttai:update_scenario`'s job).

### Step 6: Validate

Run the universal checklist, plus the type-specific checklist from the
reference file:

- [ ] `name`, `ai_instructions`, `user_friendly_description` present
- [ ] `ai_model_config` set explicitly per the "When to use which" table
- [ ] `ai_instructions` structured with `##` sections; no unresolved
      placeholders except intentional `{{ dynamic_vars }}`
- [ ] `tools_config.tools.end_session` enabled with `add_to_system_prompt: true`
- [ ] `session_analysis.is_auto_analysis: true` and `is_auto_submit: true`
- [ ] `rubrik` evaluates the correct party, categories with weights
- [ ] Cascade scenarios (Landmass): voice-pipeline blocks from
      [cascade-tts.md](references/cascade-tts.md), `strategy.welcome_instructions`
      (directive form, never quoted speech), conductor wrap-up message,
      `appearance.language_code` matches locale
- [ ] Every dynamic variable `{{ var }}` has a documented missing-value fallback

### Step 7: Create

Call `ttai:create_scenario` with the payload (and `org_id` if applicable). On
validation errors, fix the named field and retry — do not strip features to
force it through.

### Step 8: Return links

Report back with:

- **Practice link**: `https://app.toughtongueai.com/run/<scenario_id>`
- **Embed link** (if the user builds apps): `https://app.toughtongueai.com/embed/<scenario_id>`
- What was created (type, persona, evaluation focus) in 2-3 sentences.
- For private scenarios: mention `ttai:create_scenario_access_token` mints
  1-hour access tokens for sharing.

## Quick path: `ttai:generate_scenario`

For a fast draft without hand-authoring, the `ttai:generate_scenario` tool
generates `ai_instructions`, `user_instructions`, and a description
server-side from a name and context document. Use it when the user wants
speed over control, then review the output and create via
`ttai:create_scenario`. Prefer full authoring for anything the user will run
with a team.

## Pitfalls

- **Never stack questions** in voice-agent turns — one question per turn is the
  #1 authoring rule for natural calls.
- **Never quote the opening line** in `welcome_instructions` — use directive
  form ("Start with: ... Then STOP and wait."). Quoted text is delivered
  robotically and restarts on interruption.
- **Wrong rubric target** — a cold-call rubric that scores the AI caller
  instead of the lead produces useless reports.
- **Missing end_session guidance** — without explicit timing rules the agent
  either never hangs up or hangs up mid-conversation.
- The API token stays server-side; never embed `TTAI_PAT` in anything you
  generate for the user's app.

Referenced files: 6

View saved version →

---
name: scenario-refiner
description: >
  Fix and refine live ToughTongue AI scenarios from real session evidence via
  the ttai MCP server. Diagnoses whether an issue lives in ai_instructions,
  tools_config, or strategy, then applies the smallest possible edit with
  ttai:update_scenario. Use when the user says "refine the scenario", "fix the
  scenario", "the agent said X instead of Y", "it ended the call too early",
  "it skipped a step", "make it sound more natural", or pastes a transcript or
  complaint about a live scenario.
---

# Scenario Refiner

Diagnose → plan → surgical edit → verify. Never expand tokens when you can
tighten. The agent runs on a system prompt that is already long — every word
you add is a word the model has to ignore at runtime.

Read [references/runtime-behavior.md](references/runtime-behavior.md) before
diagnosing anything about prompt assembly, tool registration, conductor, or
silence mechanics.

## Prerequisites

- The **ttai** MCP server must be connected. Tool references below use the
  `ttai:` server prefix (e.g. `ttai:update_scenario`); some agents surface
  these as `mcp__ttai__update_scenario`. If the tools are missing, point the
  user at the repo README and <https://app.toughtongueai.com/developer> for a
  `TTAI_PAT` token.

## Workflow

### Step 1: Gather evidence

1. Call `ttai:list_organizations`; pass `org_id` on subsequent calls if the
   scenario belongs to an organization.
2. Fetch the scenario with `ttai:get_scenario` (needs the scenario ID — find
   it via `ttai:list_scenarios` if the user only gave a name). Read the
   **entire** `ai_instructions`, plus `strategy`, `tools_config`, and
   `session_analysis`.
3. Get the failure evidence:
   - If the user pasted a transcript or complaint, use that.
   - Otherwise pull sessions: `ttai:list_sessions` filtered by `scenario_id`
     (and date range), pick the relevant ones (e.g. lowest scores), then
     `ttai:get_sessions_batch` for details. Fetch `transcript_url` contents
     for the actual conversation text.
4. Identify the exact turn where things went wrong. Cross-reference: what did
   the scenario PRESCRIBE for that moment, and what did the agent actually DO?
   Quote both in your diagnosis.

If the transcript is in another language (Hindi, Hinglish, ...), do not
translate — the scenario is in the same language. Quote the original.

### Step 2: Diagnose root cause

Classify into one of these buckets. Each maps to a different fix location.

| Symptom | Likely cause | Fix location |
|---|---|---|
| Agent called `end_session` too early / too late / not at all | Tool timing instruction weak, or `add_to_system_prompt: false` | `ai_instructions` end-of-call block, or `tools_config.tools.end_session` |
| Agent took the wrong conversation branch | Branch trigger words too narrow, or path priority unclear | `ai_instructions` flow section (strengthen trigger list or add tie-breaker rule) |
| Agent used the wrong closing line | Closing rule not bound to the path it came from | `ai_instructions` closing section (bind closings to paths explicitly) |
| Agent skipped a prescribed step/question | "Read-the-room" rule too aggressive, or step ordering implicit | `ai_instructions` — make step 1 → step 2 a hard sequence with NEVER skip |
| Agent monologued / two questions in one turn | Style rules buried | Bold/cap a single rule in the style section; do not add a new section |
| Agent revealed AI identity or said a tool name aloud | Guardrails section missing or weak | `ai_instructions` GUARDRAILS / THINGS YOU MUST NEVER DO |
| Agent stayed silent too long, then ended the call | `silence.silence_threshold` too low, or `silence.end_session: true` | `strategy.silence` |
| Wrap-up fired during active conversation | Conductor `time_seconds` too low or `end_turn: true` | `strategy.conductor.messages` |
| Wrong voice / language / accent | Voice or language config | `appearance.voice`, `appearance.language_code`, `transcribe_config` |
| Agent said a placeholder like `{{ firstname }}` literally | Missing-context fallback not specified | `ai_instructions` CONTEXT section — add "If blank, do X" |
| Robotic opening / restarts opening when interrupted | Quoted speech in `welcome_instructions` | `strategy.welcome_instructions` — rewrite in directive form |

If the cause is architectural (template selection, tool registration,
conductor injection), open
[references/runtime-behavior.md](references/runtime-behavior.md) and cite the
relevant mechanism. Don't guess.

### Step 3: Plan the edit

Before calling any tool, write the edit out — old text and new text side by
side — and check it against these principles:

**Token discipline (in priority order):**

1. **Replace** existing text > **tighten** existing text > **add** new text
2. If you must add, ask: can I delete something stale to compensate?
3. Flag the user if the total `ai_instructions` delta exceeds +50 tokens (~3 lines)
4. Never add a "while I'm here" change. One issue = one edit.

**Effective prompt writing:**

- **Imperative voice**: "NEVER call end_session before X" not "The agent
  should not call end_session before X"
- **NEVER / ALWAYS / ONLY caps markers** for hard constraints
- **One concrete example** beats three abstract rules
- **Bind rules to triggers**: "When customer says X → do Y" beats "Be empathetic"
- **Forbid the failure mode by name**: if the agent skipped a step, write
  "NEVER skip [step], even if the issue seems minor"

**Where to put a new rule inside `ai_instructions`:**

- Hard prohibition → `## GUARDRAILS` or `## THINGS YOU MUST NEVER DO`
- Conditional behavior → inside the matching phase / path
- Tool timing → right after the prescribed closing lines
- Tone / style → the style rules block near the top

### Step 4: Apply via `ttai:update_scenario`

1. Send **only** `id` plus the fields you changed — partial updates are
   supported, and untouched fields must not be re-sent (avoids clobbering
   concurrent edits).
2. For an `ai_instructions` edit: apply your surgical replacement to the full
   fetched string and send the complete updated field. Verify no collateral
   changes (whitespace, adjacent bullets).
3. Pass `org_id` if the scenario belongs to an organization.

### Step 5: Verify and report

1. Re-fetch with `ttai:get_scenario` and confirm the change landed as planned.
2. Conclude with exactly this structure:
   - **Diagnosis** (1-2 sentences) — what went wrong and why
   - **Change** — field + before/after summary
   - **Token delta** — estimate (e.g. "+38 tokens, under the 50-token threshold")
   - **Reminder** — the change applies to **new sessions only**; running
     sessions keep their compiled system prompt

## Quick recipes

### "Agent ended the call too early"

1. Search `ai_instructions` for `end_session`. Is there an explicit
   "ONLY after closing line AND customer farewell" rule?
2. If not, add a 3-4 bullet rule block right after the closing templates.
3. Check `tools_config.tools.end_session.tool_settings.disconnectDelaySeconds`
   — too low (< 8) on emotional calls feels abrupt.

### "Closing line was generic instead of path-specific"

Strengthen the closing section with: "Based on the path you actually took
above, pick the matching closing — never substitute a generic 'thank you'."

### "Scenario scores dropped after a change"

Pull sessions before and after the change date with `ttai:list_sessions`
(`from_date` / `to_date`), compare `evaluation_results`, and check whether the
prior edit introduced the regression before adding anything new.

Referenced files: 1

View saved version →

---
name: session-analyst
description: >
  Analyze ToughTongue AI practice-session performance and build reports via
  the ttai MCP server. Pulls sessions with scores, strengths, and weaknesses,
  aggregates patterns across a team or scenario, and produces structured
  reports with improvement areas and action items. Use when the user asks
  "how is my team doing?", "top improvement areas for scenario X", "pull the
  lowest-scoring sessions", "build me a coaching report", "session trends
  this month", or wants session data turned into a deck, email, or dashboard.
---

# Session Analyst

Pull session data → aggregate patterns → produce a structured report →
optionally hand off to slides/email tools for distribution.

## Prerequisites

- The **ttai** MCP server must be connected. Tool references below use the
  `ttai:` server prefix (e.g. `ttai:list_sessions`); some agents surface
  these as `mcp__ttai__list_sessions`. If the tools are missing, point the
  user at the repo README and <https://app.toughtongueai.com/developer> for a
  `TTAI_PAT` token.

## Data model (what a session gives you)

Each session from `ttai:list_sessions` / `ttai:get_sessions_batch` includes:

- Identity: `scenario_id`, `scenario_name`, `user_name`, `user_email`
- Lifecycle: `status`, `created_at`, `completed_at`, `duration_minutes`
- `evaluation_results`: `final_score`, `strengths`, `weaknesses`, and
  `report_card[]` — per-topic `{topic, score, note, weight}`
- `improvement_results`: `improvement_areas`, `action_items`, `resources`
- `extraction_results`: structured variables (if the scenario extracts them)
- `transcript_url` (signed URL — fetch it for the conversation text) and
  `analytics_url` (human-viewable analysis page)

`report_card` topics are the backbone of aggregation: they are consistent
within a scenario because they come from its rubric.

## Workflow

### Step 1: Scope

1. Call `ttai:list_organizations`. Team analysis almost always needs an
   `org_id` — pass it on every call, along with `is_org: true` on
   `ttai:list_sessions` for org-wide data.
2. Resolve the scenario: `ttai:list_scenarios` if the user gave a name, not
   an ID.
3. Confirm the window and population: which scenario(s), which date range
   (`from_date` / `to_date`), which people (`user_email` filter), how many
   sessions.

### Step 2: Pull

- `ttai:list_sessions` with `scenario_id`, date filters, and pagination
  (`page`, `limit`). Iterate pages until you have the requested population —
  check the page metadata rather than assuming one page is everything.
- Sessions missing `evaluation_results`: either exclude them from scoring
  aggregates (note the count), or backfill — call `ttai:post_process_session`
  for each, then re-fetch after a wait and check that `evaluation_results`
  appeared. Backfill only when the user needs completeness.
- Deep dives (outliers, disputed scores): `ttai:get_sessions_batch` with the
  session IDs, then fetch `transcript_url` contents for the actual
  conversation.

### Step 3: Aggregate

Compute, at minimum:

- **Score distribution**: mean, median, range of `final_score`; flag the
  count of unanalyzed sessions excluded.
- **Per-topic breakdown**: average `report_card` score per topic, weighted by
  `weight`. The lowest topics are the improvement areas.
- **Recurring weaknesses**: cluster `weaknesses` and `improvement_areas` text
  across sessions into themes; count occurrences. Name each theme by the
  behavior, not an abstraction ("jumps to price before discovery" beats
  "communication issues").
- **Trend**: score over time if the window is long enough (week buckets work
  well); per-person averages for team views.
- **Evidence**: for each top theme, pull 1-2 short transcript quotes from
  representative sessions. Reports without evidence read as opinion.

For org-wide rollups (usage, member breakdown, time series),
`ttai:get_analytics` with `is_org_wide: true` complements per-session
aggregation.

### Step 4: Report

Use the matching template from
[references/report-templates.md](references/report-templates.md):

- **Team performance report** — "how is my team doing?"
- **Scenario health report** — "is this scenario working?" (pairs with the
  scenario-refiner skill when the answer is no)
- **Individual coaching report** — one person, one skill gap, action items

Always include: population and window, score summary, top 3-5 improvement
areas with evidence, concrete action items, and `analytics_url` links for
sessions worth reviewing by a human.

### Step 5: Distribute (optional)

If the user wants a deck, email, or document, hand the report content to
their connected tools (slides MCP, email MCP, docs). Keep the structure:
one improvement area per slide/section, evidence quote included.

## Recipes

### "Top 5 improvement areas for scenario X, last 50 sessions"

`ttai:list_scenarios` (resolve ID) → `ttai:list_sessions` (scenario_id,
limit 50, org context) → aggregate report_card topics + weakness themes →
Team performance report → deck if asked.

### "Pull the 5 lowest-scoring sessions and find out what went wrong"

`ttai:list_sessions` (scenario_id + window) → sort by
`evaluation_results.final_score` ascending, take 5 →
`ttai:get_sessions_batch` → fetch transcripts → diagnose common failure
patterns → if the fault is in the scenario (not the users), hand off to the
**scenario-refiner** skill with the diagnosis.

### "How did [person] do this month?"

`ttai:list_sessions` (user_email + from_date) → per-topic averages, trend
across their sessions → Individual coaching report with action items from
`improvement_results`.

### Automated post-call coaching (webhook-driven)

For teams wiring this into pipelines (e.g. every real sales call gets a
coaching report): see the recipe in
[references/report-templates.md](references/report-templates.md) —
`ttai:create_session` ingests an external transcript against a coaching
scenario, `ttai:post_process_session` triggers analysis, poll until
`evaluation_results` appears, then format and send the report.

## Pitfalls

- **Don't average across different scenarios' report cards** — topics and
  weights differ per rubric. Aggregate per scenario, compare qualitatively.
- **Small samples**: below ~10 analyzed sessions, report observations, not
  statistics — and say so.
- **Session status**: only `completed` sessions have meaningful duration and
  results; exclude `in_progress` and `failed` from aggregates.
- **Privacy**: coaching reports name individuals. Confirm the audience before
  distributing anything per-person to a group channel.

Referenced files: 1