Skip to content

tough-tongue/toughtongue-skills / skills/ttai-agent

ttai-agent

Verified

Creates, 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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall