Transcribe audio with Rev.ai: submit jobs by URL, read transcripts, summaries and captions.
Scored across 8 tools
Each tool targets a distinct resource+action (submit/poll/list/delete jobs, plus account, transcript, captions, summary), so boundaries are mostly clear. The only mild overlap is revai_get_transcript vs revai_get_captions vs revai_get_summary, all reading a job's output, but descriptions distinguish format and purpose well.
Every tool follows a uniform prefix + verb_noun pattern (revai_get_*, revai_list_*, revai_submit_job, revai_delete_job) with consistent snake_case. No deviations or mixed conventions.
Eight tools map cleanly onto the transcription domain's core operations with no filler. Each tool earns its place, and the count sits comfortably in the well-scoped 3-15 range.
Covers the full submit -> poll -> read -> delete lifecycle plus account and multiple output formats (text, segments, SRT/VTT, summary), which is strong. Minor gaps: no way to cancel/delete an in-progress job and no custom-vocabulary or streaming options, but core workflows are covered.
WRITE: permanently delete a finished (transcribed or failed) job with its media and transcript. This cannot be undone. A job still in progress cannot be deleted. DELETE /jobs/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Rev.ai job id (the `id` from revai_submit_job or revai_list_jobs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the destructiveHint annotation by disclosing exactly what is destroyed (job plus its media and transcript), that the action is irreversible, and that only terminal-state jobs qualify. These are the operative behavioral details an agent needs before committing to 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?
Four short clauses, front-loaded with the 'WRITE' classification and the permanence warning. Every sentence carries distinct information (effect, irreversibility, precondition, endpoint) with no 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?
For a single-parameter destructive tool with no output schema, the description covers effect, durability, and preconditions well. The only minor gap is what the caller receives on success (e.g., empty response vs. status), which is left unstated.
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 schema description already explains that job_id comes from revai_submit_job or revai_list_jobs. The description only restates the path variable as {id}, adding no meaning beyond the structured data, 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 and resource ('permanently delete a ... job') and adds scope qualifiers (finished/transcribed/failed). The destructive, irreversible nature and the in-progress exclusion make it unmistakable against read-oriented siblings like revai_get_job and revai_list_jobs.
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 clear precondition for use: only finished jobs may be deleted, and in-progress jobs are rejected. It does not need to name a fallback tool since no sibling offers an alternative deletion path, but it stops short of an explicit 'use X instead' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Rev.ai account behind the token: email, free, purchased, total and invoiced balance (USD) and whether HIPAA is on. GET /account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the concrete return fields (balances, HIPAA flag), which is useful, but says nothing about auth/token requirements beyond the phrase 'behind the token', nor about rate limits or freshness of balance data.
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?
A single dense sentence front-loads the resource and the returned fields, followed by the endpoint path. Nothing is wasted, though the trailing 'GET /account' is mild redundancy for a description that already names the resource.
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 no parameters and no output schema, the description carries the return-value burden and discharges it by listing the fields an agent will receive. It is nearly complete for such a simple read tool; only auth/scoping details are left implicit.
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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument call scoped entirely by the supplied token, and adds no misleading parameter expectations.
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 resource (the Rev.ai account behind the token) and enumerates exactly what it returns: email, free/purchased/total/invoiced balance in USD, and HIPAA status. It is clearly distinguishable from the job/transcript siblings, though it never explicitly names them.
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?
There is no guidance on when to call this versus anything else, no prerequisites, and no mention that it is the only account-scoped tool. Usage is only inferable from the tool name and the fact that siblings all operate on jobs/transcripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Captions for a transcribed job as SRT (default) or WebVTT. Long files are paged by character: repeat with next_offset until it is null. For multichannel jobs pass speaker_channel. GET /jobs/{id}/captions.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | srt (default) or vtt. | |
| job_id | Yes | Rev.ai job id (the `id` from revai_submit_job or revai_list_jobs). | |
| offset | No | Start position from the previous reply's next_offset (default 0). | |
| max_chars | No | Most characters to return in one reply, 1000-20000 (default 15000). | |
| speaker_channel | No | Channel to caption, for jobs submitted with speaker_channels_count. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe-read profile (readOnlyHint, destructiveHint=false, openWorldHint). The description adds genuinely non-obvious behavior: character-based paging driven by next_offset, and the speaker_channel requirement for multichannel jobs. It does not cover rate limits or exactly what the payload contains, keeping it short of a 5.
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, front-loaded with what the tool returns, followed by the paging rule and the multichannel rule, closing with the endpoint. No filler and every clause carries actionable 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 no output schema, the description carries the return-value burden and does so adequately by stating the payload is SRT or WebVTT and is paged via next_offset. Missing only minor detail such as the response shape of next_offset alongside the caption text.
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 the parameters, their bounds, and defaults are already fully documented in the schema. The description echoes the format default and the offset/speaker_channel semantics without adding syntax or constraints beyond what the schema states, matching the baseline 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?
States a specific verb+resource ('Captions for a transcribed job') plus the two output formats and the underlying endpoint GET /jobs/{id}/captions. The resource is inherently distinct from siblings like revai_get_transcript and revai_get_summary, though the description never explicitly names those alternatives to sharpen the contrast.
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 operational guidance: repeat the call with next_offset until it is null for long files, and pass speaker_channel for multichannel jobs. It does not however tell the agent when to prefer captions over the sibling revai_get_transcript, so there are no stated exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One transcription job by id: status (in_progress, transcribed, failed), timestamps, duration, language, failure reason. Poll this until status is transcribed. GET /jobs/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Rev.ai job id (the `id` from revai_submit_job or revai_list_jobs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered; the description adds genuine extra context by disclosing the status lifecycle values and the polling workflow. It omits rate-limit/polling-interval guidance that Rev.ai documents, keeping it from a 5.
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?
The content is front-loaded and every clause carries information: scope, return fields, polling action, endpoint. The telegraphic fragment style ('One transcription job by id:') is efficient but slightly clipped relative to a well-formed sentence.
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 no output schema, the description compensates by naming the key response fields and the status values an agent must branch on, plus the polling rule. Coverage is strong for a single-parameter read tool; only polling cadence and terminal-state handling are absent.
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?
There is one parameter at 100% schema description coverage, and the schema already explains that the id comes from revai_submit_job or revai_list_jobs. The description adds nothing further about the id's format or acceptance, 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?
The description states a specific verb and resource ('One transcription job by id') and enumerates the returned fields (status, timestamps, duration, language, failure reason), which clearly separates it from revai_list_jobs. It never names a sibling explicitly, so it stops short of a 5.
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?
'Poll this until status is transcribed' gives concrete operational guidance that most definitions lack, and it implicitly chains to fetching the transcript afterwards. It does not state when to prefer revai_get_transcript or revai_get_summary instead, so no exclusions are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The summary of a transcribed job. It exists only if the job was submitted with summarization_type. Paged by character like revai_get_transcript. GET /jobs/{id}/transcript/summary.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Rev.ai job id (the `id` from revai_submit_job or revai_list_jobs). | |
| offset | No | Start position from the previous reply's next_offset (default 0). | |
| max_chars | No | Most characters to return in one reply, 1000-20000 (default 15000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/non-destructive. The description adds two behaviors beyond them: the conditional existence of the resource and character-based paging. It does not describe the summary's shape, but for a read tool with annotations this is solid added context.
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, front-loaded with the core fact and the precondition before the paging hint. The trailing endpoint path is mildly redundant but cheap and locates the call precisely.
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?
For a one-required-param read tool with no output schema and full schema coverage, the description covers purpose, precondition, and paging convention. It leaves the summary's content format unspecified, but an agent has enough to invoke 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 description coverage is 100% and both offset and max_chars are already documented there. The description's 'paged by character' note echoes the schema rather than extending it, 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 ('The summary of a transcribed job') and immediately scopes it with the availability precondition. It also names the sibling revai_get_transcript as the paging analogue, so an agent can distinguish it from the transcript tool 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 a clear precondition — the summary exists only if the job was submitted with summarization_type — which tells the agent when this call will yield data. It does not explicitly state when to prefer this over revai_get_transcript, but the shared paging model and the name make the relationship obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The transcript of a transcribed job. format=text (default) is plain text with speaker labels and timestamps; format=segments is a list of {speaker, start, end, text} per speaker turn (seconds). Long transcripts are paged: repeat with next_offset until it is null. GET /jobs/{id}/transcript.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text (default) or segments. | |
| job_id | Yes | Rev.ai job id (the `id` from revai_submit_job or revai_list_jobs). | |
| offset | No | text: character position; segments: segment index. Use the previous reply's next_offset (default 0). | |
| max_chars | No | Most characters to return in one reply, 1000-20000 (default 15000). | |
| group_channels_by | No | Multichannel jobs only: how to group words into turns. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context on top: the response is paged and must be re-fetched with next_offset until null, and each format changes the shape of what comes back. It stops short of noting error behavior or rate limits, so not a 5.
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 compact sentences cover format semantics, paging, and endpoint with no filler. The opening fragment 'The transcript of a transcribed job.' is slightly circular, but the rest is front-loaded and information-dense.
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 no output schema, the description carries the return-value burden and does so for both formats plus pagination. group_channels_by is left to the schema (which documents it as multichannel-only), and the non-applicability of that parameter in the description is a minor gap.
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 the baseline would be 3, but the description goes further by explaining that format=segments returns {speaker, start, end, text} per turn in seconds and that text includes speaker labels and timestamps, and by tying offset/next_offset to the paging loop. That is meaning the schema alone does not convey.
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 the resource (the transcript of a job) and the underlying endpoint GET /jobs/{id}/transcript, and spells out the two output formats. It does not differentiate itself from siblings such as revai_get_captions or revai_get_summary, so an agent must infer which of the three 'retrieve artifact' tools applies.
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?
Paging guidance ('repeat with next_offset until it is null') and the default of format=text give implied operating instructions, but there is no explicit when-to-use vs when-not-to-use, and no routing against revai_get_captions/revai_get_summary. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transcription jobs from the last 30 days, newest first: id, status (in_progress, transcribed, failed), name, duration, language, failure reason. Page with starting_after = the previous reply's next_starting_after. GET /jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Jobs per page, 1-100 (default 20). | |
| starting_after | No | Return jobs older than this job id (exclusive), from next_starting_after. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavior beyond that: a bounded 30-day retention window, deterministic newest-first ordering, the enumerated status values, and the pagination chain, which is useful operational context.
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?
A single dense sentence plus one paging sentence and the endpoint. Scope and sort order are front-loaded, and every clause (returned fields, paging rule, HTTP route) carries 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 no output schema, the description compensates by enumerating the returned fields (id, status, name, duration, language, failure reason) and the status enum values, and it explains the pagination mechanism. Nothing essential for a correct list call 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% and both parameters (limit with its 1-100 range and default of 20, starting_after with its exclusive/older-than semantics) are already fully documented there. The description's mention of starting_after only restates what the schema says, 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?
States a specific verb and resource ('List transcription jobs') plus the governing scope (last 30 days), sort order (newest first), and the exact fields returned. An agent can distinguish this list operation from revai_get_job, revai_submit_job, and revai_delete_job without opening a 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?
Provides clear usage context by explaining the 30-day window, default ordering, and the paging contract (starting_after = previous reply's next_starting_after). It does not explicitly name the alternative for fetching one job or state exclusions, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: start an asynchronous machine transcription job for an audio or video file at a public URL. It uses Rev.ai credit (free credit first). Returns the job with status in_progress; then poll revai_get_job and read the result with revai_get_transcript. Human transcription is not offered. POST /jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Spoken language as an ISO 639-1 code (en, en-us, en-gb, es, fr, de, ...). Default en. | |
| metadata | No | A note stored with the job and returned with it (for example your own reference). | |
| verbatim | No | Keep every false start and disfluency (default true for machine jobs). | |
| media_url | Yes | Direct download URL of the audio or video file. Rev.ai fetches it; it must be reachable without login. | |
| speakers_count | No | Number of speakers, if known (English, Spanish, French); improves speaker labels. | |
| filter_profanity | No | Mask profanity in the transcript. | |
| forced_alignment | No | More accurate per-word timestamps (en, fr, it, de, es). | |
| skip_diarization | No | Do not label speakers. | |
| skip_punctuation | No | Return words without punctuation. | |
| summarization_type | No | Also create a summary, read later with revai_get_summary. | |
| remove_disfluencies | No | Drop 'ums' and similar fillers. | |
| delete_after_seconds | No | Delete the job and its data this many seconds after it completes. | |
| speaker_channels_count | No | Number of audio channels with one speaker each. Billed per channel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds valuable context beyond these: it is asynchronous, returns a job with status in_progress, consumes Rev.ai credit (free credit first), and requires the media to be at a public URL. It does not detail auth needs or rate limits, but the added workflow and cost context is substantial.
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-loads 'WRITE:' and the core action, then gives the follow-up workflow in two compact sentences. Every sentence carries useful information and there is no 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?
For a 13-parameter write tool with no output schema, the description supplies the essential behavioral context: async job creation, credit consumption, returned status, and exact follow-up tools for polling and retrieving the transcript. The schema fully covers parameter details, so nothing critical 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 the schema already documents all 13 parameters thoroughly. The description adds only a slight framing ('audio or video file at a public URL') that largely restates the media_url schema description, so 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?
States a specific verb and resource ('start an asynchronous machine transcription job') and clearly distinguishes it from human transcription, which is not offered. It also names the sibling tools for follow-up (revai_get_job, revai_get_transcript), so an agent can identify its place in the workflow 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?
Provides clear context for when to use it (to start a machine transcription job for a public media URL) and explicitly routes to revai_get_job and revai_get_transcript afterward. It also notes that human transcription is not offered, but does not compare against other submission alternatives (none exist) or detail failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe public audio/video URLs and retrieve transcripts, SRT, and VTT subtitles.
AI transcription API: turn voice memos, meetings and audio URLs into text and SRT subtitles.
Transcribe audio and video to text, SRT or VTT. Summaries, translation. Optional OAuth sign-in.
Transcribe audio & video to text for AI agents: 100+ languages, speaker labels, webhooks.
Add one secure layer between your agents and this server.
