Update to Speak AI

{
  "description": "Analyze interviews, user research calls, and customer conversations across many Speak AI recordings. Use this when you need themes across a set of calls, verbatim quotes with speaker names and timestamps, sentiment, or a comparison between two time periods, segments, or folders. Covers finding the right recordings with search_media and list_media, reading the transcripts and insights of a folder or of specific media ids and doing the analysis yourself, citing every claim, and pulling exact quotes out of transcripts. Triggers on requests like analyze these interviews, research synthesis, find the themes, what did customers say about pricing, pull quotes, compare Q1 and Q2 calls, sentiment across recordings, and code these interview transcripts.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 288
    }
  ],
  "name": "research-analysis",
  "skill_md_contents": "---\nname: research-analysis\ndescription: Analyze interviews, user research calls, and customer conversations across many Speak AI recordings. Use this when you need themes across a set of calls, verbatim quotes with speaker names and timestamps, sentiment, or a comparison between two time periods, segments, or folders. Covers finding the right recordings with search_media and list_media, reading the transcripts and insights of a folder or of specific media ids and doing the analysis yourself, citing every claim, and pulling exact quotes out of transcripts. Triggers on requests like analyze these interviews, research synthesis, find the themes, what did customers say about pricing, pull quotes, compare Q1 and Q2 calls, sentiment across recordings, and code these interview transcripts.\nlicense: MIT\nmetadata:\n  server: \"@speakai/mcp-server\"\n  server-version: \"1.41.1\"\n  categories: \"research\"\n---\n\n# Research analysis across many recordings\n\nThe user's explicit instructions take priority over this skill. When they ask for something different from the steps below, do what they asked, and confirm with them before any action that deletes, overwrites, or sends data outside Speak AI.\n\nYou use this skill when someone asks a research question that spans more than one\nrecording. The work always follows the same shape. Find the right recordings, confirm\nthey are ready to read, scope the set, read it and do the analysis yourself, then check\nthe exact words against the transcripts so the answer is defensible.\n\nThe Speak AI MCP server has 189 tools. This skill uses tools from five of the fifteen\ncategories: search-analytics (3 tools), magic-prompt (13 tools), media (19 tools),\nfolders-views (11 tools), and custom-fields (4 tools). Every tool named below exists.\nDo not invent tool names. If you need something that is not listed here, check\n`tools.json` in the repository before you call anything.\n\n## Connection\n\nThe remote endpoint is `https://api.speakai.co/v1/mcp`, transport type\n`streamable-http`, with OAuth 2.1 and Dynamic Client Registration. The user approves\nonce and you never handle a key.\n\nThere are three ways to authenticate and they are not interchangeable. Keys come from\nhttps://app.speakai.co/developers/apikeys.\n\n- **Remote MCP endpoint**, `https://api.speakai.co/v1/mcp`: OAuth, or\n  `Authorization: Bearer <speak-api-key>`.\n- **stdio mode and the CLI**: an API key configured on the user's machine, as described\n  at <https://docs.speakai.co/mcp/authentication>. There is no header to set.\n- **The REST API directly**: your API key on every call, in `x-speakai-key` or as\n  `Authorization: Bearer <key>`. There is no access token to fetch.\n\nYou do not need raw REST for this skill, since the tools cover it. If you do call it\ndirectly, authentication is documented at <https://docs.speakai.co/mcp/authentication>.\n\n## Step 1. Find the right recordings\n\nThis is the step people skip, and it is the step that decides whether the answer is\nright. Never analyze the whole workspace on the first pass. You will end up with an\naverage of everything, and you will not be able to say which calls each point came from.\n\n### Which finder to use\n\n| You know | Use | Why |\n| --- | --- | --- |\n| A topic, phrase, or theme, and you do not know which files contain it | `search_media` | Full text search across transcripts, insights, and metadata. Returns matching media with excerpts, sentiment, and tags. |\n| A folder, a date range, a name pattern, or a media type | `list_media` | Structured listing with filters, sorting, and pagination. Cheaper and more predictable than search. |\n| Nothing yet, and the user described a set in words | `list_folders` then `get_folder_info` | Research work is usually already organized into folders by study, quarter, or segment. |\n| The set already, and you want an answer about it | `get_transcript`, `get_media_insights`, or `list_media` with `include` | This is the reading step, not the finding step. |\n\nThe important distinction: `search_media` and `list_media` return media ids. The analysis\ncomes after, from the transcripts and insights of exactly those ids. If you start reading\nbefore you have fixed the set, you cannot say which recordings an answer covers. Find\nfirst, then read.\n\nDocs:\nhttps://docs.speakai.co/mcp/tools/search-analytics/search_media/\nhttps://docs.speakai.co/mcp/tools/media/list_media/\n\n### Using search_media\n\nInputs: `query` (required), `startDate`, `endDate`, and `filterList`.\n\n```json\n{\n  \"query\": \"pricing objection\",\n  \"startDate\": \"2026-01-01T00:00:00.000Z\",\n  \"endDate\": \"2026-06-30T23:59:59.000Z\",\n  \"filterList\": [\n    {\n      \"fieldName\": \"tags\",\n      \"fieldOperator\": \"include\",\n      \"fieldValue\": [\"enterprise\"],\n      \"fieldCondition\": \"and\"\n    }\n  ]\n}\n```\n\n`fieldName` accepts `category`, `folderId`, `mediaId`, `mediaType`,\n`sentimentNegative`, `sentimentPositive`, `speaker`, `tags`, `recorderId`, and\n`fields`. `fieldOperator` accepts `include`, `notInclude`, `contain`, `notContain`,\n`greaterThan`, and `lessThan`. `fieldCondition` is `and` or `or`.\n\nThe date range matters more than it looks. If you leave `startDate` and `endDate` out,\nthe search covers the current calendar year only. A study that ran last autumn will\nreturn nothing and the empty result will look like a real answer. Always set the range\nexplicitly when the user mentions any period, and widen it before you report that\nnothing was found.\n\n### Using list_media\n\nInputs you will actually use: `folderId`, `filterName`, `mediaType`, `from`, `to`,\n`sortBy`, `page`, `pageSize`, `isFavorites`, and `include`.\n\n```json\n{\n  \"folderId\": \"fld_example_q2_interviews\",\n  \"from\": \"2026-04-01T00:00:00.000Z\",\n  \"to\": \"2026-06-30T23:59:59.000Z\",\n  \"sortBy\": \"createdAt:desc\",\n  \"pageSize\": 50,\n  \"include\": [\"speakers\", \"keywords\", \"sentiment\"]\n}\n```\n\n`include` embeds extra data inline so you avoid one call per file. It accepts\n`transcription`, `keywords`, `speakers`, `sentiment`, `custom`, and `fields`.\n\nDo not combine `include: [\"transcription\"]` with a large `pageSize`. Every result then\ncarries a full transcript and an oversized response is rejected outright, so you lose\nthe whole page instead of one file. Keep `pageSize` around 10 when you pull\ntranscripts inline, and page through.\n\n## Step 2. Confirm the recordings are readable\n\nCall `get_media_status` for anything you plan to quote or analyze. The states run\nqueued, then preparing, then processing, then preparingAnalysis, then processed, or failed.\n\nOnly `processed` media has insights. `get_media_insights` needs the processed state.\n`get_transcript` is more forgiving: it works on processed media and also returns the\npartial in progress transcript while a meeting bot is still recording.\n\nIf a file is still processing, do not treat it as absent and do not silently drop it.\nTell the user which files are not ready, run the analysis on the ones that are, and say\nso in the answer. A synthesis over 11 of 14 interviews is useful. A synthesis that\nquietly claims to cover 14 is not.\n\nDocs:\nhttps://docs.speakai.co/mcp/tools/media/get_media_status/\nhttps://docs.speakai.co/mcp/tools/media/get_media_insights/\nhttps://docs.speakai.co/mcp/tools/media/get_transcript/\n\n## Step 3. Scope the set\n\nDecide which recordings the analysis covers before you read anything. Pick the narrowest\nset that answers the question.\n\n- Specific media ids. Use this when you found the set in step 1. This is the default\n  choice for research work because you can name every source.\n- A whole folder. Pass its `folderId` to `list_media` and page through. Use this when the\n  folder is the study and the user wants everything in it.\n- The entire workspace. Use this only when the user explicitly asks about everything,\n  and say in your answer that the scope was the whole workspace.\n\nWhatever the scope, keep the list of media ids you actually read. Being able to answer\n\"which calls is this from\" is the point of the exercise.\n\nIf the study is not in a folder yet, create one with `create_folder` and move the files\nwith `bulk_move_media`. That turns an ad hoc set into something the user can re-run\nlater. Ask before you reorganize anything, since moving media changes what other people\nsee.\n\n## Step 4. Read the set and do the analysis\n\nRead the content of every recording in the set, then do the analysis yourself.\n\n- `list_media` with the `folderId` or date range and `include: [\"transcription\"]` returns\n  transcripts inline. Keep `pageSize` around 10 and page through, as described in step 1.\n- `get_transcript` with a `mediaId` returns one transcript with speaker labels and\n  timestamps. Use it when you only need a few files, or when a file was too large to come\n  back inline.\n- `get_media_insights` with a `mediaId` returns that file's topics, sentiment, keywords,\n  action items, and summaries. It is a quick way to see what each recording is about\n  before you read it closely.\n\nWork through the question the user asked. For a theme analysis, for example: list the\nrecurring themes, count how many participants raised each one, and quote one verbatim\nline per theme with the recording and speaker it came from. Leave out a theme that only\none participant raised unless the user wants those too.\n\nKeep track of the source for every claim as you go: the recording name or media id, the\nspeaker, and the timestamp. Citations are much harder to recover afterwards.\n\nWhen the set is too large to read in full, say so. Use `search_media` with a focused\n`query` to find the passages that matter, read those recordings in full, and tell the\nuser which recordings you read and which you only saw through search excerpts or\ninsights.\n\nSomeone may already have run this analysis in Speak's AI Chat. `get_chat_messages`\naccepts a `query` that searches text across past prompts and answers, and returns them\nwith their `references`. It paginates with `page` and `pageSize` (default 25, max 500).\nTreat what you find there as a lead, and check it against the transcripts before you\nrepeat it.\n\nDocs:\nhttps://docs.speakai.co/mcp/tools/media/get_transcript/\nhttps://docs.speakai.co/mcp/tools/media/get_media_insights/\nhttps://docs.speakai.co/mcp/tools/magic-prompt/get_chat_messages/\n\n## Step 5. Pull the exact quotes\n\nVerification is a separate step and it uses different tools.\n\nBefore you present a quote, confirm it against the source.\n\n1. `get_transcript` with a `mediaId` returns the full transcript with speaker labels and\n   timestamps. This is the source of truth for a verbatim quote.\n2. `get_media_insights` with a `mediaId` returns the generated topics, sentiment,\n   keywords, action items, and summaries for one file. Use it for per file sentiment and\n   for keyword counts that you want to compare across files.\n3. `get_captions` returns subtitle formatted output. Use it only when the user wants\n   captions or a clip label, not for reading.\n\nCheck that the quoted words appear in the transcript before you present them. If a\nquoted line is not in the transcript, drop it and say the claim could not be verified.\n\nSpeaker labels are the usual reason a quote looks wrong. A transcript may say\n\"Speaker 0\" rather than a name. Call `get_transcript` first to read the current labels,\nthen `update_transcript_speakers` for one file, or `bulk_update_transcript_speakers` to\napply one mapping across several files at once. Two cautions. The speaker id is the\ncurrent label, not a fixed identifier, so ids you captured in an earlier turn can be\nstale. Renaming a speaker to a name another speaker already holds is refused as a\ncollision.\n\nDocs:\nhttps://docs.speakai.co/mcp/tools/media/update_transcript_speakers/\nhttps://docs.speakai.co/mcp/tools/media/bulk_update_transcript_speakers/\n\n## Step 6. Compare across time or segment\n\nThere are three usable comparison patterns. Pick one and stay in it.\n\n**By date.** Build two sets with the same filters and different date ranges, using\n`from` and `to` on `list_media` or `startDate` and `endDate` on `search_media`. Analyze\neach set separately with the same questions, then compare the two results. Do not mix the\nperiods while you read, because you will lose track of which period a claim came from.\n\n**By segment.** Keep each segment in its own folder and run the same analysis on each\n`folderId`. Where segments are marked with tags instead of folders, filter with\n`search_media` and `filterList` on `tags` and read the resulting media ids.\n\n**By participant.** Go through the recordings one at a time and note an answer for each.\nYou get one answer per recording, which is what you need to count how many participants\nsaid a thing rather than writing a summary that says \"most\".\n\nCustom fields make segment comparisons repeatable. `list_fields` shows what already\nexists. `create_field` adds one, and a field can carry a `prompt` that populates it\nautomatically. `update_multiple_fields` sets values across a whole folder or a list of\nmedia ids in one call, so you can label a cohort once and filter on it forever after.\nReuse an existing field before you create a new one, since duplicate fields with slightly\ndifferent names make every later comparison ambiguous.\n\n```json\n{\n  \"folderId\": \"fld_example_q2_interviews\",\n  \"fields\": [\n    { \"id\": \"fld_field_example_segment\", \"value\": \"enterprise\" }\n  ]\n}\n```\n\nDocs:\nhttps://docs.speakai.co/mcp/tools/custom-fields/list_fields/\nhttps://docs.speakai.co/mcp/tools/custom-fields/update_multiple_fields/\nhttps://docs.speakai.co/mcp/tools/folders-views/list_folders/\nhttps://docs.speakai.co/mcp/tools/folders-views/get_folder_info/\n\n## Step 7. Save what is worth keeping\n\n- `create_folder_view` saves a column layout for a folder so the next person opens the\n  study with the right fields visible. `get_folder_views` lists what already exists.\n- `toggle_media_favorite` flags the key recordings so the team can find them again.\n\n## Bringing in written feedback\n\nResearch is not only recordings. Survey free text, support tickets, and pasted notes\nanswer the same questions, and Speak AI treats them the same way once they are in.\n\n`create_text_note` takes the text and stores it as media. `get_text_insight` returns the\nsame shape of analysis a recording gets: topics, sentiment, keywords, entities.\n`reanalyze_text` regenerates that analysis after the content changes, and\n`update_text_note` edits the note's name, content, or metadata.\n\nBecause a text note becomes media, it lands in the same folders, matches the same\n`search_media` queries, and can be read and analyzed alongside the recordings. So a study can cover fifteen interviews and two hundred survey comments in one\nanswer rather than two disconnected ones.\n\nAnalyze the note before asking about it. A note that has not finished analyzing returns\nempty insights, the same as a recording.\n\n## Edge cases that actually bite\n\n**Media still processing.** Insights are missing until the state is `processed`. Check\n`get_media_status` before you analyze, name the files you skipped, and never present a\npartial set as complete.\n\n**Empty results that are not really empty.** `search_media` defaults to the current\ncalendar year. This is the single most common cause of a false negative. Widen the date\nrange and retry before you tell anyone there is nothing. Also try `list_media` with\n`filterName`, since a term that appears only in a file name will not always surface the\nway you expect through full text search.\n\n**Oversized responses.** `list_media` with `include: [\"transcription\"]` and a large\n`pageSize` gets rejected as a whole. Reduce `pageSize`, or drop `transcription` from\n`include` and fetch transcripts one at a time with `get_transcript` for the files you\nactually quote.\n\n**Pagination.** `list_media` uses zero based `page` with `pageSize` up to 100.\n`get_chat_messages` uses zero based `page` with `pageSize` up to 500. `list_folders`\nallows up to 500 per page. `search_media` has no page parameter, so narrow it with\n`filterList` and the date range instead of expecting to page through it. Never conclude\n\"there are only N interviews\" from a single unpaged call.\n\n**Permissions.** Everything runs as the connected account, so you only see media that\naccount can reach. An access error is not a transient failure. Do not retry it in a\nloop. Report which item was refused and let the user fix access.\n\n**Stale speaker ids.** A speaker id is the current label. If you renamed speakers, or\nsomeone else did, re-read with `get_transcript` before the next rename. A rename that\nalready succeeded is a safe no-op, so do not retry a call that reported success.\n\n**Sentiment as a headline number.** Per file sentiment from `get_media_insights` is a\nsignal about one recording. Averaging it across a study and reporting a single number\nhides the split that the user is asking about. Report the range and the outliers, and\nname the recordings at each end.\n\n**Scope drift across questions.** A follow up question often moves to a different set\nof recordings. When the user changes the subject, go back to step 1 and fix the new set\nbefore you answer, rather than reusing the media ids from the earlier question.\n\n## Tool reference\n\n| Tool | Category | Use |\n| --- | --- | --- |\n| `search_media` | search-analytics | Full text search across transcripts, insights, metadata |\n| `get_media_statistics` | search-analytics | Workspace level counts and processing status breakdown |\n| `list_media` | media | Filtered, sorted, paginated listing, with optional inline data |\n| `get_media_status` | media | Processing state before you analyze or quote |\n| `get_transcript` | media | Verbatim text with speaker labels and timestamps |\n| `get_media_insights` | media | Topics, sentiment, keywords, action items, summaries |\n| `get_captions` | media | Subtitle formatted output |\n| `update_transcript_speakers` | media | Rename speakers in one file |\n| `bulk_update_transcript_speakers` | media | Apply one speaker mapping across files |\n| `bulk_move_media` | media | Move a found set into a study folder |\n| `toggle_media_favorite` | media | Flag key recordings |\n| `get_chat_messages` | magic-prompt | Search and read past AI Chat answers and their references |\n| `list_folders` | folders-views | Discover studies and segments |\n| `get_folder_info` | folders-views | Folder detail and contents |\n| `create_folder` | folders-views | Make a study folder |\n| `create_folder_view` | folders-views | Save a column layout for the study |\n| `get_folder_views` | folders-views | List saved views for a folder |\n| `list_fields` | custom-fields | See existing segment and coding fields |\n| `create_field` | custom-fields | Add a field, optionally auto populated by a prompt |\n| `update_multiple_fields` | custom-fields | Set field values across a folder or media list |\n\nPer tool documentation follows the pattern\n`https://docs.speakai.co/mcp/tools/<category-id>/<tool_name>/`.\n"
}