tough-tongue/toughtongue-skills / skills/ttai-agent
ttai-agent
VerifiedCreates, edits, and refines Tough Tongue AI Scenarios, the definitions behind voice agents (sales calls, lead qualification, demos, screening, support, booking) and practice roleplays (negotiations, interviews, coaching). Writes ai_instructions, ai_model_config, strategy, tools_config, and rubrik through ttai:create_scenario and ttai:update_scenario. Also resolves the personal or organization workspace, checks plan and balance, places or cancels SIP calls, schedules or cancels meeting bots, mints private Scenario links, grounds a Scenario in the user's documents with knowledge FileBases, and troubleshoots ttai MCP sign-in. Use when the user wants a voice agent or practice Scenario created or improved ("create a voice agent", "the agent ends calls too early", "make it sound more natural"), a call placed, a meeting bot sent, or a Tough Tongue AI account question answered. Not for reports across many sessions (ttai-session-analyst) or browser demo steps (ttai-browser-demo-builder).
references/mcp/tools.md
View on GitHub# MCP tools
The `ttai` MCP server (`https://api.toughtongueai.com/api/public/mcp`) is the
action surface: 15 public tools, named `verb_resource`. Tools
appear as `ttai:<name>` (some clients show `mcp__ttai__<name>`). The connected
`tools/list` and each tool's input schema are authoritative; this file is the
map.
## Contents
- Tools
- Reading: workspace
- Reading: resource types
- Read recipes
- Confirm before acting
- Updating a Scenario
- FileBases
- Tool notes
- Directory endpoint
## Tools
The workspace is read through one tool, records through two; each write family
keeps its own tools because risk hints are per tool.
| Do | Tools |
| ---------------- | -------------------------------------------------------- |
| Guide | `ttai:read_guide` |
| Read workspace | `ttai:get_workspace_info` (`sections`) |
| Read records | `ttai:list_resources`, `ttai:get_resource` |
| Read a schema | `ttai:get_schema` (`"scenario"`) |
| Scenarios | `ttai:create_scenario`, `ttai:update_scenario` |
| Sessions | `ttai:analyze_session`, `ttai:set_user_metadata` |
| FileBases | `ttai:create_filebase`, `ttai:write_filebase` |
| Bots | `ttai:schedule_bot`, `ttai:cancel_bot` (meeting and phone) |
| Access | `ttai:create_token`, `ttai:authenticate_browser` |
Skip any tool prefixed `int_` or titled "Internal…": it is not part of the
public API. Every tool except `ttai:read_guide` accepts an optional `org_id`; omit it for the personal
workspace. First calls: `ttai:read_guide`, then `ttai:get_workspace_info`.
## Reading: workspace
`ttai:get_workspace_info(org_id?, sections?, query?, start_date?, end_date?)`
answers who you are and where you work. It returns `scope` (personal |
organization), `org_id`, your `role`, and the sections you ask for (others
`null`):
| Section | Holds | Default |
| --------------- | ------------------------------------------------------------- | ------- |
| `me` | your id, name, email, preferences | yes |
| `organizations` | every membership: `id` (your `org_id`), name, slug, role, `quota_enabled` | yes |
| `plan` | effective entitlements for the scope (SIP, models, limits) | yes |
| `balance` | personal or org wallet; your quota when quotas are on | yes |
| `members` | org only: id, email, name, role, `quota_available`; `query` filters name/email (max 100, `total`) | no |
| `usage` | by Scenario; org editors add a daily series + `member_usage`; `start_date` / `end_date` | no |
Roles: `view` < `edit` (Admin in the app) < `owner`; `no_access` = end users. Rate limit: 30 calls per minute per token; respect a live
rate-limit response.
## Reading: resource types
`ttai:list_resources(type, query?, filters?, include_fields?, cursor?, limit?,
include_total?)` lists; `ttai:get_resource(type, id, filters?,
include_fields?, paths?)` reads one record (`id` is always required). The server's MCP
instructions name every type, and `ttai:read_guide` lists each type's filter
names — read it when unsure. These skills write
`ttai:list_resources(sessions)` as shorthand for `ttai:list_resources` with
`type: "sessions"`; extra words in the parentheses name the argument to set.
| Type | Holds |
| -------------------------------------- | -------------------------------------------------------- |
| `scenarios` · `scenario-versions` | agent definitions and their history |
| `sessions` | runs and results; `include_fields: [transcript]` for text |
| `bots` | meeting bots and phone calls (`kinds`: meeting, phone) |
| `filebases` | app and knowledge FileBases (filter `kind`); `paths` returns file text |
| `sip-trunks` · `collections` | dial-out trunks, courses |
| `knowledge-bases` · `custom-functions` | legacy RAG bases, HTTP tools |
| `avatar` | system faces |
- `filters` is a map of the type's own filter names, e.g.
`{"scenario_ids": ["…"], "statuses": ["completed"]}`. One value where a list
is expected is accepted.
- `query` is free text where the type supports it; on `scenarios` it is the
title search.
- Typed lists return `{items, next_cursor, total?}`; default `limit` 25, max
100. Pass `next_cursor` back as `cursor`.
- Directory types (`sip-trunks`, `knowledge-bases`, `custom-functions`,
`avatar`) return common metadata; `data` is empty until you request that
type's `include_fields`. Secret values come back masked.
- Date filters accept ISO 8601 dates or timestamps; a date-only lower bound
means 00:00 UTC, an upper bound 23:59:59 UTC. No timezone means UTC.
## Read recipes
- **Exact count** → `list_resources` with `limit: 1, include_total: true`. Never
page through results to count. For an org-wide Session count pass `org_id`;
do not list every Scenario and echo its IDs. `bots` has no `include_total`:
page with `cursor` to count.
- **Scenario by title** → `list_resources(scenarios, query: "…")`, then
`get_resource(scenarios, id)`.
- **Scenario history** (needs edit access) →
`list_resources(scenario-versions, filters: {scenario_id})`, then
`get_resource(scenarios, id, filters: {version_id})`. Omit the filter for
current.
- **Sessions by person, date, or learning result** → `list_resources(sessions,
filters: {user_email | from_date | to_date | hasLearning | is_org})` — these
switch to the enriched legacy list (`is_org: true` for the org-wide admin
view). It takes at most one `scenario_ids` value, no `query` or
`include_fields`, and `limit` up to 500.
- **Transcript** → `get_resource(sessions, id, include_fields: [transcript])`.
Several known IDs → `list_resources(sessions, filters: {ids: […]},
include_fields: [...])`.
- **Calls and bots** → `list_resources(bots, filters: {kinds: [phone]})`
(`include_fields: [failure]` for why a call failed).
- **Usage, durations, top Scenarios, member activity** →
`get_workspace_info(sections: [usage], start_date, end_date)`.
- **Balance and plan limits** → `get_workspace_info(sections: [plan, balance])`.
- **Org members and quotas** → `get_workspace_info(org_id, sections: [members])`.
## Confirm before acting
State the exact target (phone number, meeting URL, Scenario ID, audience,
timing) and get the user's go-ahead before any of these. Never dial or dispatch
a bot from inferred data. The server's tool annotations flag the same risks
(destructive: `update_scenario`, `write_filebase`, `cancel_bot`; open world:
every tool below except `write_filebase` and `create_token`); confirm
even when a client hides them.
- `ttai:schedule_bot` — `kind: "phone"` dials real phones (one unscheduled
entry rings immediately); `kind: "meeting"` sends a visible bot into a real
meeting.
- `ttai:cancel_bot` — destructive; cancels a call or meeting bot only before it
starts.
- `ttai:update_scenario` — overwrites the fields you send; changes the live
agent.
- `ttai:write_filebase` — replaces or deletes files in a FileBase.
- `ttai:analyze_session` — fills only missing results (never re-scores); may
fire the Scenario's post-session hooks.
- `ttai:authenticate_browser` — opens a live browser on the Scenario's browser
profile.
- `ttai:create_token` — grants access by link; a `scenario_access` email can
create or reuse a user record.
## Updating a Scenario
- Fetch the field schema once: `ttai:get_schema("scenario")`. Both
write tools take one `scenario` object with those fields.
- `ttai:create_scenario` rejects `id`; requires `name` and `ai_instructions`.
Omitting `tools_config` installs a broad default tool set — send it
explicitly.
- `ttai:update_scenario` requires `id`. Omitted fields stay unchanged; sent
fields replace stored values, with these merge rules:
- `strategy`, `appearance`, `memory`, `session_analysis`, `transcribe_config`,
`meeting_config`, `access` merge one level: each key you send replaces that
key (sending `strategy.silence` keeps `strategy.conductor`; sending
`strategy.conductor` replaces all its `messages`).
- `tools_config.tools.<tool>` merges `should_register`,
`add_to_system_prompt`, and `tool_settings` per tool; `tool_settings` is
replaced whole. Read it, merge, and write the full object, or you drop keys
such as the browser tool's saved `contextId` and recorded `steps`.
- Everything else is replaced whole: `ai_model_config` (resend `tts_voice_id`
and the rest of the stamp), `stages`, `rubrik`, `processed_rubrik`,
`auto_update_config`, ID lists, `user_metadata`.
- `save_as_version` (1–100 characters) archives the prior state, then
applies the change. The label names the new version you are saving; the
archived copy keeps its own earlier label ("Initial version" if it had
none).
- `get_resource(scenarios, id)` omits linked-resource IDs
(`knowledge_base_ids`, `knowledge_filebase_ids`, `custom_function_ids`,
`pre_connect`); the create/update response returns the full authoring state.
- Type rules: `default` is the normal agent; `super` needs `stages` with a
non-empty first stage and flows, and a Landmass model; `quiz`, `coding`
(`coding_question`), and `meet_assist` need their schema-defined
configuration. Never send `super_agent`.
- Plan checks run on write: Scenario count limits, Ocean model access, and
`multimodal_analysis` can return `403`.
- Edits apply to new sessions only.
## FileBases
A FileBase is a folder of files with a `kind`: `app` (an Agent Desktop app) or
`knowledge` (plain files an agent reads). Read them as type `filebases`.
- `ttai:create_filebase(kind: app | knowledge, name, title, description?, visibility?, storage?)`
→ an empty FileBase in the current org or personal space. `name` is a slug,
fixed at create, unique per space. An app requires `storage`: `cdn` (fast)
or `private` (files never fetchable by link). Knowledge omits it.
- Access: an org FileBase is visible to every member; its creator and role
EDIT+ edit it. `visibility: "private"` keeps it to its creator; set it at
create (no MCP tool changes it). Featured FileBases are read-only (`403`).
List rows carry `visibility`, `featured`, `org_id` and `editable`; check
`editable` before writing.
- `ttai:write_filebase(id, files, delete)` → whole-file upserts by relative path
(no leading `/`), then deletes. The receipt has `kind`, `written`,
`deleted`, `files` (the tree after), `revision`, an advisory `warning`, and
`missing`: convention files still to add. Write the entry file in the first
call: `README.md` for an app, `index.md` for knowledge.
- List: `list_resources(filebases, filters: {kind}, query?)`. Read before
rewriting: `get_resource(filebases, id, paths: [...])` (≤ 20 files) returns
`{filebase, files}`.
- Apps: `README.md` (the agent's manual), `src/App.tsx`, and `data/**` the
live agent rewrites; no `spec.json`. Results carry `view_url`, the preview
page. Attach with the Scenario's `agent_desktop` tool. The ttai-agent-apps
skill covers building, checking, and attaching apps.
### Knowledge FileBases
Not the legacy Knowledge Base (`knowledge-bases`, `knowledge_base_ids`, tool
`knowledge_base_search`), which is created in the web app only.
- Entry: root `index.md`, not `README.md`: what the base covers and which file
answers what, linking every other file. Keep it under 4 KB; a short index is
inlined in the agent's prompt.
- Workflow: the user attaches PDFs or docs → distill them into focused
markdown files plus `index.md` → `create_filebase(kind: knowledge)` →
`write_filebase` (index first) → confirm, then link the id on the Scenario.
- Link: `knowledge_filebase_ids` on `create_scenario` / `update_scenario`
replaces the whole list, and a Scenario read omits it. Keep the ids the last
create/update response showed. Current list unknown → say linking replaces
any attached knowledge and get a go-ahead. Each id must be visible to you
(yours, your org's, public, or featured; else `400`). Find featured bases
with `list_resources(filebases, filters: {kind: knowledge})`.
- Sharing: the Scenario link is the grant. Anyone who can run the Scenario has
the agent read the base, whatever its visibility. No `view_url` or
`filebase_view` link.
- Runtime: no `tools_config` entry needed. The prompt names each linked base;
the agent gets two tools:
- `getKnowledgeBite(filepath, start?, lines?)` reads a line window of
`<base name>/<path>`; a bare base name reads `index.md`.
- `listKnowledgeBites(base)` lists the base's files with sizes.
## Tool notes
- `ttai:read_guide` returns the server's usage guide, the same text as the
`ttai://guide/mcp-agent` resource. Call it once at the first action in a
conversation unless the guide is already in context.
- On connect the server also sends MCP `instructions`: a short index of this
map. `tools/list` is ordered by importance (the guide first, `int_` tools
last).
- System avatars:
`list_resources(avatar, filters: {type: static | hybrid | live, provider})`.
- `get_workspace_info` `balance` is personal minutes, or the org wallet plus
the caller's quota when quotas are on; `plan` is role, tier identity/status,
effective limits — no price or billing history.
- `ttai:schedule_bot` takes one `bot` object with `kind`:
- `kind: "phone"` — `scenario_id`, `sip_trunk_id` (an outbound trunk from
`list_resources(sip-trunks)`), `entries` of E.164 `phone_number` + optional
`user_name` and per-entry `dynamic_vars`, optional `scheduled_ts` and
`scenario_version_id`. One entry dials directly; several form a batch the
dialer works through within minutes, inside `office_hours` when set. Needs
a SIP-enabled plan and enough balance. Optional `call_policy` covers every
call in the batch: `office_hours` (IANA `timezone`, `weekdays`, one
`start`–`end` window in `HH:MM`) and `retry` (`max_retries` 1–5, one
`delays_minutes` entry per retry, `retry_on_failed` default `true`,
`extraction_conditions` that must all match, `check_recent_calls`).
Needs edit access to the Scenario; private Scenarios are allowed.
Procedure:
[../entities/scenario-engine.md](../entities/scenario-engine.md#calling-campaigns).
- `kind: "meeting"` — joins Google Meet, Zoom, or Teams visibly. Required:
`scenario_id`, `meeting_url`, `meeting_provider`
(`google-meet`|`zoom`|`teams`), and an AI-identifying `bot_name`. Optional:
`scheduled_ts`, `scenario_version_id`, `dynamic_vars` (sent as `t_*`),
`embed_overrides` (iframe controls such as `speed`, `bg`, `theme`; no `t_`
prefix), `artifact_screenshare` (default `true`: screenshares supported
artifacts), `login_required` (a signed-in Google Meet bot). `meeting_url`
may hold several URLs, one per line. Needs a paid plan and edit access to
the Scenario.
- Follow a bot: `ttai:schedule_bot` returns `bots[].bot_id` (meeting),
`call_id` (one phone entry), or `batch_id` (several entries). Read status
with `get_resource(bots, id)` or
`list_resources(bots, filters: {batch_ids: [batch_id]})`; the bot's
`session_id` is the conversation, readable once it ends.
- `ttai:cancel_bot(id)` cancels either kind only before it starts; a bot
already in its meeting or a ringing call cannot be stopped here.
- `session_credentials: "bot_uc"` is a server-side setting: the session belongs
to the deploying Tough Tongue AI user and the agent gets that user's MCP
tools. Omitted, it runs as an anonymous guest with no MCP tools. Nothing is
read from the user's machine. A meeting bot for a private Scenario needs it;
without it the server rejects the bot. Otherwise omit it unless requested.
- No MCP tool ingests calls held elsewhere (dialer, Gong, Zoom); that is the
REST API's
[Create session](https://app.toughtongueai.com/docs/api-reference/sessions/create).
- `ttai:analyze_session(session_id)` queues the missing analysis/extraction
configured on the Scenario. Poll
`get_resource(sessions, id, include_fields: [processing])` until
`post_session_status.state` leaves `running` (`idle` = done, `failed` =
error), then read the results. A 429 "Analysis limit reached for this
session." is final; any other 429 is a rate limit: wait, then retry.
- `ttai:set_user_metadata(type: "sessions", id, set?, unset?)` labels a session
with your own keys (deal stage, disposition, follow-up owner): `set` writes
string, number, or boolean values; `unset` removes keys. Needs EDIT on the
Scenario. Reads return them as `user_metadata`; MCP list filters cannot
match on them, so filter after fetching.
- `ttai:create_token` takes one `request` with a `type` and returns `{type,
token, expires_at, url}`:
- `type: "scenario_access"` — `scenario_id`, `valid_for_hours` (1–168),
optional `email` or `self_billed: true` (runs and bills as you; omit
`email`). `url` is an iframe embed.
- `type: "filebase_view"` — an app `filebase_id`, `valid_for_hours`
(≤ 24). `url` opens the app without a sign-in.
- `ttai:authenticate_browser(req)` needs edit access and a Scenario whose `browser`
tool is registered. It returns a single-use `embed_url` (about 20 minutes)
where a human signs in to the Scenario's browser profile, then clicks
**Save & close session** so the profile stays signed in.
`enable_recording_tool: true` adds a tab for recording replayable steps.
Hand the link to the user; the agent cannot log in for them.
- Collections are read-only through MCP.
## Directory endpoint
`https://api.toughtongueai.com/api/public/mcp/directory` is a policy-limited
surface for connector directories. It has the same 15 tools, but its
`ttai:schedule_bot` accepts only `kind: "meeting"` (no outbound dialing). Inspect
`tools/list` before inferring what it can do. Place calls from a full MCP
client.
## Key Files
- [clients.md](clients.md) — connect a client, OAuth, troubleshooting
- [../operating-model.md](../operating-model.md) — scope and action loop
- [../entities/scenario-engine.md](../entities/scenario-engine.md) — channels
and results
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |