Use your WhisperAI transcripts in Claude, ChatGPT and other MCP clients. Transcribe a public media URL or upload audio and video, with optional speaker labels and a language choice. Search your library, read transcripts with timestamps, export them as text or SRT and VTT captions, pull an AI summary, and translate, rename or delete recordings. Sign in with your WhisperAI account over OAuth. It works on every plan, the free one included, and uses your plan's normal minutes.
Scored across 12 tools
Most tools have clear, distinct purposes: upload vs URL transcription, reading vs exporting vs summarizing, renaming, deleting, translating, and account usage are well separated by descriptions. Minor ambiguity remains around refresh_upload_authorization, which is oddly infrastructural, and around get_transcript also serving as a polling/status tool.
All tool names use a consistent snake_case verb_noun pattern such as start_upload, get_transcript, rename_transcript, and delete_transcript. The few longer names like refresh_upload_authorization still follow the same convention.
Twelve tools is well within a reasonable range for a transcription platform with upload, URL import, listing, reading, summarizing, exporting, translating, renaming, deleting, and account queries. Each tool corresponds to a recognizable user action or lifecycle step.
The surface covers the core recording lifecycle from upload and URL import through polling, reading, summarizing, exporting, translating, renaming, and deleting. Minor gaps exist around editing transcript content or managing/inspecting translations as first-class resources, but nothing blocks the primary workflows.
Permanently deletes a recording, its transcript, summary, and translations. This cannot be undone. Call it only when the user explicitly asks to delete a specific recording. Only the recording's owner can delete it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts |
| Name | Required | Description |
|---|---|---|
| id | Yes | The deleted recording id |
| deleted | Yes | True on success |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: it names the collateral data destroyed (transcript, summary, translations), states irreversibility, and discloses the ownership authorization constraint. These are exactly the facts an agent needs before firing a destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, destructiveness and irreversibility front-loaded before the usage constraint. Every sentence carries distinct information; nothing is repeated from the annotations verbatim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, a fully described single parameter, and an output schema handling return values, the remaining burden is behavioral nuance — destruction scope, irreversibility, ownership, and intent gating — all of which are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the id param already points at list_transcripts as its source. The description adds no further parameter guidance such as what happens with an invalid or already-deleted id, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (permanently deletes) plus an enumerated resource scope (recording, transcript, summary, translations). This clearly separates it from read/rename/export siblings, though no sibling is named explicitly as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a genuine gating condition: call only when the user explicitly asks to delete a specific recording, which excludes speculative or automated use. It lacks a named fallback (e.g. rename_transcript or export_transcript) for the common 'user really wants X instead' case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a download link for a completed transcript as a PDF, Word document, plain text, or SRT/VTT subtitles. Call it when the user wants to download, save, or export a transcript as a file; to read a transcript's content into the conversation use get_transcript instead. Present the returned link to the user — it expires after 30 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts | |
| format | Yes | File format: "pdf", "docx", "txt", "srt", or "vtt" | |
| includeSpeakers | No | Include speaker labels in pdf/docx/txt exports (default true) | |
| includeTimestamps | No | Include segment timestamps in pdf/docx/txt exports (default false) |
| Name | Required | Description |
|---|---|---|
| format | Yes | The exported format |
| filename | Yes | Suggested filename for the downloaded file |
| downloadUrl | Yes | Direct download link — show it to the user as a clickable link |
| expiresInSeconds | Yes | How long the link stays valid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds genuine value with the 30-minute link expiry and the instruction to surface the link to the user. It also scopes the tool to *completed* transcripts, which is a meaningful precondition. Minor gap: it doesn't say what happens when a transcript is still processing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose, then use/avoid routing, then the operational caveat about link expiry. Front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values needn't be explained, yet the description still adds the one behavioral detail an agent needs (link expiry and presenting the link). For a 4-param export tool this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with enums and per-field descriptions for id, format, includeSpeakers, and includeTimestamps, so the schema does the heavy lifting. The description restates the format list but adds nothing about the boolean flags or how they interact with each format. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ("creates a download link for a completed transcript") and enumerates the supported output formats. It is immediately distinguishable from the read-oriented sibling get_transcript, which the description explicitly names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use condition ("when the user wants to download, save, or export a transcript as a file") and names the alternative plus the condition that selects it ("to read a transcript's content into the conversation use get_transcript instead"). No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the signed-in user's WhisperAI plan, transcription minutes used and remaining this month, and the service's capabilities. Call it before large transcription jobs, or when the user asks about their plan, usage, limits, or what WhisperAI can do.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | Yes | Effective plan, e.g. "free", "pro", "enterprise" |
| minutesUsed | Yes | Transcription minutes used this month |
| capabilities | Yes | What the WhisperAI service can do |
| minutesLimit | Yes | Monthly minute allowance (-1 = unlimited) |
| maxFileSizeMb | Yes | Maximum upload file size in MB for this plan |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, closed-world, and non-destructive behavior, so the bar is low. The description adds useful semantics: the result is implicitly scoped to the authenticated user with no identifying input, and it names the data categories returned. It doesn't mention freshness/caching, but that's minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is returned and followed by when to call it. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema documenting the return shape, rich annotations, and no parameters, the description covers everything an agent needs: what it returns, who it applies to, and when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4. The description reinforces this by framing the result as the signed-in user's account, making it clear no identity parameter is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Returns) plus the exact resource: the signed-in user's plan, transcription minutes used/remaining, and service capabilities. It is clearly distinguishable from all siblings, which operate on transcripts, uploads, and translations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete call triggers — before large transcription jobs, or when the user asks about plan, usage, limits, or capabilities. It stops short of an explicit exclusion or a named alternative, but no sibling tool overlaps this function, so the guidance is effectively complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the transcript of one recording by id, chunked by character offset because transcripts can be very long. Call it after list_transcripts to read a transcript's content, or to poll a recording that is still processing (it returns the current status instead of text until transcription completes). Formats: plain text, JSON segments, or SRT/VTT subtitles.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts | |
| limit | No | Max characters to return (default 20000, max 25000) | |
| format | No | Output format: "text" (default), "segments" (JSON array with timings/speakers), "srt" or "vtt" subtitles | |
| offset | No | Character offset to start from (default 0; use nextOffset to continue) | |
| includeSpeakers | No | Label text with speaker names when diarization exists (default true) | |
| includeTimestamps | No | Prefix each line of text output with its start time (default false) |
| Name | Required | Description |
|---|---|---|
| text | No | The requested chunk of the transcript |
| title | No | Recording title |
| offset | No | Character offset this chunk starts at |
| status | Yes | Recording status — text fields are present only when "completed" |
| hasMore | No | True when more of the transcript remains |
| message | No | Human-readable note when the transcript is not ready |
| language | No | Transcript language code |
| nextOffset | No | Pass as `offset` to fetch the next chunk (absent on the last chunk) |
| totalLength | No | Total transcript length in characters |
| speakerNames | No | Speaker id → display name map when diarization exists |
| durationSeconds | No | Audio duration in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add what they can't: it explains that results are paginated by character offset and, importantly, that an in-progress recording returns status instead of text. That polling behavior is non-obvious and genuinely valuable; pagination token handling is left to the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core behavior, then usage, then format options. No filler and no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and full schema description coverage, the description covers exactly the non-structured facts an agent needs: chunking, polling semantics, and available formats. Nothing required to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds rationale the schema lacks: why offset exists (transcripts can be very long) and how the format enum maps to user intent (plain text vs JSON segments vs subtitles). It stops short of explaining includeSpeakers/includeTimestamps interplay.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the transcript of one recording by id') plus the defining constraint that output is chunked by character offset. It also distinguishes itself from the summarization/export siblings by describing what it returns (raw text, segments, subtitles) rather than a summary or an exported file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing ('Call it after list_transcripts') and a second valid use case — polling a recording still processing. It does not explicitly say when to prefer get_transcript_summary or export_transcript, so the sibling routing is incomplete but the primary context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the AI-generated summary of a completed recording: executive summary, key points, action items, and speaker profiles. Call it when the user wants the gist, decisions, or follow-ups from a recording without reading the full transcript. Summaries are generated automatically after transcription; if none exists yet the result says so.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts |
| Name | Required | Description |
|---|---|---|
| exists | Yes | False when no summary has been generated yet |
| content | No | Legacy full summary text |
| message | No | Explanation when no summary exists |
| createdAt | No | When the summary was generated |
| keyPoints | No | Key points discussed |
| actionItems | No | Action items identified |
| potentialIssues | No | Risks or issues raised |
| speakerProfiles | No | Per-speaker profiles/contributions, when available |
| executiveSummary | No | High-level summary paragraph |
| keyRecommendations | No | Recommendations extracted from the discussion |
| importantInformation | No | Notable facts, figures, and dates |
| prioritizedActionItems | No | Action items with owner/priority details, when available |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: summaries are AI-generated automatically after transcription, and if no summary exists yet the result says so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences with zero waste. The core return value is front-loaded, followed by usage context and an important missing-summary behavior note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required parameter, full schema coverage, existing output schema, and clear read-only annotations. The description covers what it returns, when to use it, and what happens when no summary is available, so an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single id parameter is documented as coming from list_transcripts. The description adds no additional parameter guidance, but with full schema coverage the baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: returning the AI-generated summary of a completed recording. It further specifies the contents (executive summary, key points, action items, speaker profiles), which clearly distinguishes it from get_transcript and list_transcripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: call it when the user wants the gist, decisions, or follow-ups without reading the full transcript. It implicitly contrasts with reading the full transcript but does not explicitly name get_transcript as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists recordings stored in WhisperAI (newest first by default) with optional full-text search over titles and transcript content. Use it to find a recording id before reading or changing that recording.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order (default "newest") | |
| limit | No | Max items to return, 1-50 (default 20) | |
| query | No | Full-text search over titles and transcript content (min 3 characters) | |
| cursor | No | Opaque pagination cursor from a previous result's nextCursor | |
| status | No | Only return recordings with this processing status |
| Name | Required | Description |
|---|---|---|
| items | Yes | The matching recordings |
| total | Yes | Total recordings matching the filters |
| hasMore | Yes | True when more results exist beyond this page |
| nextCursor | Yes | Pass as `cursor` to fetch the next page (null when exhausted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about default ordering and search scope, but does not mention pagination behavior, limits, or filtering by status beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core behavior and followed by a concise usage pointer. Every sentence earns its place with no redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, output schema, and annotations, the description is nearly complete for an agent to call this tool correctly. It could mention pagination or status filtering explicitly, but those are well covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented. The description reinforces the purpose of 'query' and 'sort' at a high level but does not add syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Lists recordings stored in WhisperAI') and clarifies the default ordering and optional full-text search. The phrase 'before reading or changing that recording' implicitly distinguishes it from sibling tools like get_transcript, rename_transcript, and delete_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case: find a recording id before reading or changing that recording. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select this tool over sibling read/mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keeps an existing uploader authorized without changing its settings or starting a transcription.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The original uploader's account ID |
| Name | Required | Description |
|---|---|---|
| expiresInSeconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description only needs to add scope. It does add value by stating that settings are unchanged and no transcription begins, which is genuine disambiguation. It does not say what 'keeping authorized' entails (whether an expiry is extended, how long, or what happens if the uploader was deleted), leaving the actual side effect unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One well-formed sentence with the scope constraints front-loaded and no padding. It is arguably too terse for a tool whose core behavior is never actually explained, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations and an output schema cover safety and return shape, and the single parameter is fully documented, so the description only owes an explanation of what 'refresh' does. It never states the effect on authorization lifetime or failure conditions, which is the one gap that matters for a renewal tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single documented parameter, so the baseline of 3 applies. The description adds no semantics about the userId beyond what the schema already says ('the original uploader's account ID').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific act on a specific resource: keeping an existing uploader authorized. It implicitly separates itself from start_upload and transcription tools by denying that it starts a transcription, though it never names a sibling directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied — refresh an uploader that already exists — and the 'without... starting a transcription' clause steers away from start_upload. But there is no explicit when-to-use callout or stated prerequisite that the uploader must already exist and be known to the caller.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes the title of an existing recording. Call it when the user wants to rename a recording or give an auto-titled upload a meaningful name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts | |
| title | Yes | New title (1-255 characters) |
| Name | Required | Description |
|---|---|---|
| id | Yes | The recording id |
| title | Yes | The title after renaming |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds only that the target must be an existing recording; it says nothing about what happens when the id is unknown, whether the old title is recoverable, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences; the action statement comes first and the usage trigger follows. No filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, a fully documented two-parameter schema, and complete annotations, the description covers what an agent needs to select and call it. The only meaningful omission is error behavior for an invalid or non-existent recording id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id, title) including the 1-255 length constraint are already documented in the schema. The description mentions only the title concept generically and adds no format, sourcing, or validation detail beyond it — baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('changes the title of an existing recording') and adds the auto-titled-upload use case, which pins down the intent. It is trivially distinguishable from siblings like delete_transcript, retranscribe_transcript, or export_transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to call it: 'when the user wants to rename a recording or give an auto-titled upload a meaningful name.' It does not name a when-not condition or a competing sibling, but no sibling plausibly competes for this action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an existing recording again with agreed settings, without uploading its audio again. Creates a new recording and preserves the original transcript. Each intentional run uses normal plan minutes (duration / 60); explain this and agree the changes with the user before calling. Use get_transcript and get_account to check duration and allowance first. Only the recording's owner can retranscribe it, after its current run finishes or fails. Omitted settings keep the source values. Reuse the same requestId and arguments on retries; never create another requestId just because output or a queue response is delayed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The existing recording whose stored audio to reuse | |
| title | No | ||
| settings | No | Agreed changes only; omitted fields keep the source recording's settings. Empty arrays/strings or null clear optional settings. | |
| requestId | Yes | Unique ID for this requested retranscription. Reuse exactly this ID and arguments on network retries; generate a new ID only for a separately requested run. |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| message | Yes | |
| duplicate | Yes | |
| recordingId | Yes | |
| estimatedMinutes | Yes | |
| sourceRecordingId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing cost (duration/60 plan minutes), the additive-but-non-destructive effect (new recording, original preserved), ownership and run-state preconditions. Retry semantics via requestId are also spelled out. Only a small gap remains around how the new recording relates to the original (e.g., linkage in list_transcripts).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and outcome, then layered constraints and finally retry guidance – a sensible order. It is dense with six sentences, but each carries a distinct rule (cost, verification, permission, state, merge behavior, idempotency) rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, and annotations cover the safety profile. Given a 4-parameter nested schema, the description supplies every operational fact an agent needs: cost model, consent requirement, precondition checks, ownership, merge behavior, and retry discipline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% and already documents id and most settings, but the description adds the merge semantics ('Omitted settings keep the source values') and the requestId retry contract (reuse same ID and arguments), which are the two parameters most likely to be misused. Nested settings fields like customPrompt and importantTerms remain undocumented in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Run an existing recording again') and immediately distinguishes it from upload-based siblings by noting it works 'without uploading its audio again'. It also clarifies the side effect: a new recording is created while the original transcript is preserved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names prerequisites and alternatives: use get_transcript and get_account to check duration and allowance, and only the owner may call it, and only after the current run finishes or fails. It also states a user-consent step (explain minute consumption and agree changes) before calling, which is exactly the when-to-use guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare an uploader with the agreed transcription settings before the user selects local audio/video files. Accepts up to 20 files per selection, all using the displayed settings; each file gets its own recording ID. Review language, speaker labels/names/count, style and other preferences with the user first; omitted settings use their saved preset or service defaults. The widget displays the applied settings. Uploading is the final action and immediately starts transcription, using normal plan minutes. Call start_upload again to change settings before uploading. Authorization renews automatically while connected. After upload the widget reports each recording ID; poll get_transcript for each. To change settings later, use retranscribe_transcript without re-uploading. For a public media URL use transcribe_url.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional note shown to the user above the uploader | |
| language | No | Spoken language code, "auto", or "multi-auto" | |
| translateTo | No | Translate the result into this language, or null to disable translation | |
| customPrompt | No | ||
| speakerCount | No | Known speaker count, or null for automatic detection | |
| speakerNames | No | Known speaker names; use names or roles, not both | |
| speakerRoles | No | Known speaker roles when names are unknown | |
| speakerLabels | No | Detect and label speakers | |
| importantTerms | No | ||
| transcriptionStyle | No |
| Name | Required | Description |
|---|---|---|
| settings | Yes | |
| expiresInSeconds | Yes | Lifetime of the temporary upload token. The widget renews it automatically; this is not an uploader deadline. |
| maxFilesPerBatch | Yes | |
| supportsMultipleFiles | Yes | |
| autoRefreshAuthorization | Yes | |
| startsTranscriptionOnUpload | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint false, destructiveHint false, idempotentHint false); the description adds substantial context beyond them: uploading consumes normal plan minutes, transcription starts immediately on upload, authorization renews automatically while connected, omitted settings fall back to saved presets or service defaults, and results arrive via the widget with a recording ID to poll on get_transcript.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the pre-upload review requirement, and most sentences carry distinct information (re-entry, cost, polling, alternatives). It is on the long side at roughly nine sentences, with some UI-widget detail that could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, yet the description still supplies the workflow an agent needs: the widget surfaces settings and recording IDs, then the agent polls get_transcript per recording. Combined with the default-fallback behavior and cost note, nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 70%, and the description adds genuinely useful semantics not in the schema — the omitted-parameter fallback rule (saved preset or service defaults) and the pairing of speaker labels with name/count. It does not address customPrompt, importantTerms, translateTo, or note, leaving four parameters to the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Prepare an uploader with the agreed transcription settings' — plus concrete scope details (up to 20 files, each file gets its own recording ID). It explicitly routes away from two siblings: retranscribe_transcript for later setting changes and transcribe_url for public media URLs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions ('Review language, speaker labels/names/count, style and other preferences with the user first'), describes the re-entry pattern ('Call start_upload again to change settings before uploading'), and names alternatives with the condition selecting them (transcribe_url for public URLs, retranscribe_transcript for post-hoc changes).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads a publicly reachable audio or video file (up to 200MB) and starts transcribing it, counting against the user's plan minutes. Call it when the user shares a direct link to a media file they want transcribed; for files on the user's device use start_upload instead. Returns immediately with a recording id — poll get_transcript for the result.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Publicly reachable http(s) URL of the audio/video file | |
| title | No | Title for the new recording (defaults to the file name from the URL) | |
| language | No | Spoken language code, e.g. "en", "es" (default: auto-detect) | |
| translateTo | No | Also translate the finished transcript into this language code (e.g. "es", "fr") as soon as transcription completes | |
| customPrompt | No | Free-form context about the audio that guides transcription (e.g. "a sales call about the Q3 renewal"). Use speakerNames/importantTerms for names and terms; use this only for context that fits neither. | |
| speakerCount | No | Exact number of speakers in the audio, when the user knows it | |
| speakerNames | No | Names of the people speaking, in no particular order (e.g. ["Lucas", "Eman"]) — the transcript labels speakers with these names instead of "Speaker 1/2" | |
| speakerRoles | No | Roles of the people speaking when names are unknown (e.g. ["doctor", "patient"] or ["interviewer", "candidate"]) — the transcript labels speakers with these roles. Supply names or roles, not both. | |
| speakerLabels | No | Detect and label different speakers (default true) | |
| importantTerms | No | Names, jargon, or uncommon terms likely to appear in the audio — improves their spelling in the transcript | |
| transcriptionStyle | No | Transcription style preset (default "standard"): "verbatim" keeps every filler word and false start, "clean_readable" removes them, plus domain presets like "interview_qa", "legal", "medical", "technical" |
| Name | Required | Description |
|---|---|---|
| status | Yes | Always "processing" on success |
| message | Yes | What happens next |
| recordingId | Yes | Id of the new recording — poll it with get_transcript |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds value beyond them: a 200MB size ceiling, the fact that processing consumes the user's plan minutes, and that the call is asynchronous, returning immediately with a recording id. Those are exactly the operational facts annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler, and the most decision-relevant information (what it does, size limit, when to use it vs. start_upload) is front-loaded. The async/poll note closes it out efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values needn't be detailed, yet the description still tells the agent it returns immediately with a recording id and to poll get_transcript — the critical control-flow fact. Combined with the quota and size limits, nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 11 parameters is already documented in the schema, including enum meanings and default behavior. The description only restates the URL constraint (publicly reachable, 200MB) and adds no parameter guidance beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (downloads a media file from a URL and starts transcribing) with concrete scope (publicly reachable, up to 200MB). It explicitly distinguishes itself from start_upload for local files, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger ("when the user shares a direct link to a media file they want transcribed"), an explicit exclusion with a named alternative ("for files on the user's device use start_upload instead"), and the follow-up step (poll get_transcript). This is the full when/when-not/next pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts translating a completed transcript into another language. Translation runs asynchronously and uses the user's plan quota. Call it when the user asks for a transcript in a different language; if a translation already exists it is returned instead of being redone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Recording id from list_transcripts | |
| targetLanguage | Yes | Target language code, e.g. "es", "fr", "de", "ja" |
| Name | Required | Description |
|---|---|---|
| status | Yes | "processing" while the translation job runs, "completed" when done |
| content | No | The translated text when the translation is already completed |
| message | Yes | What happened / what to do next |
| recordingId | Yes | The recording id |
| targetLanguage | Yes | The requested target language |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses three things the agent cannot infer: the work runs asynchronously, it consumes the user's plan quota, and an existing translation is returned rather than regenerated. That is real added value on top of readOnlyHint=false and idempotentHint=true. It stops short of telling the agent how to observe completion or retrieve the result of an async job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, then the trigger condition and the dedup caveat. Nothing is repeated from the title and every clause carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and the description covers the async, quota, and caching behaviors that matter for invoking it. The one residual gap is how an agent should follow up on a job started asynchronously — whether by polling get_transcript or some other means.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (id, targetLanguage) are already documented with sourcing and example language codes. The description adds only the notion of a "completed" transcript as a validity condition and does not extend parameter meaning further, which is the expected baseline when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (translating) on a specific resource (a completed transcript) into a new language. The verb is unique among siblings — retranscribe_transcript, get_transcript, export_transcript all describe clearly different operations — so an agent can route without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Call it when the user asks for a transcript in a different language" gives an explicit trigger condition, and "if a translation already exists it is returned instead of being redone" tells the agent re-invocation is safe. What is missing is a stated exclusion — e.g. that it cannot be used on in-progress recordings, or that retranscribe_transcript is the alternative when the source language itself is wrong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
delete_transcriptexport_transcriptget_accountget_transcriptget_transcript_summarylist_transcriptsrefresh_upload_authorizationrename_transcriptretranscribe_transcriptstart_uploadtranscribe_urltranslate_transcript
Add one secure layer between your agents and this server.