Skip to main content
Glama

Transcribe from URL

transcribe_url

Downloads a publicly reachable audio/video file or completed, unencrypted HLS (.m3u8) stream (up to 200MB total) and starts transcribing it, counting against the user's plan minutes. Call it when the user shares a direct media or finite HLS link 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "url": "<url>"
    },
    "name": "transcribe_url"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesPublicly reachable http(s) URL of the audio/video file or completed HLS (.m3u8) playlist
titleNoTitle for the new recording (defaults to the file name from the URL)
languageNoSpoken language code, e.g. "en", "es" (default: auto-detect)
translateToNoAlso translate the finished transcript into this language code (e.g. "es", "fr") as soon as transcription completes
customPromptNoFree-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.
speakerCountNoExact number of speakers in the audio, when the user knows it
speakerNamesNoNames of the people speaking, in no particular order (e.g. ["Lucas", "Eman"]) — the transcript labels speakers with these names instead of "Speaker 1/2"
speakerRolesNoRoles 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.
speakerLabelsNoDetect and label different speakers (default true)
importantTermsNoNames, jargon, or uncommon terms likely to appear in the audio — improves their spelling in the transcript
transcriptionStyleNoTranscription 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"

Output Schema

NameRequiredDescriptionDefault
statusYesAlways "processing" on success
messageYesWhat happens next
recordingIdYesId of the new recording — poll it with get_transcript

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / url / description
      Previous value: -"Publicly reachable http(s) URL of the audio/video file"New value: +"Publicly reachable http(s) URL of the audio/video file or completed HLS (.m3u8) playlist"
  2. First observed

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already say readOnlyHint=false and openWorldHint=true, so the description's job is to add context, which it does: 200MB cap, plan-minute cost, immediate return with a recording id, and polling get_transcript. What it does not cover is what happens on failure (bad URL, oversized file, live stream) or whether a failed job still consumes minutes, which matters for a destructiveHint=false but billable async operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each doing distinct work: capability, routing/alternative, then the async return and poll path. The size and billing limits are front-loaded in the first clause rather than buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter async creation tool with an output schema, the description covers the essentials: input constraints, cost, and how to retrieve the result, so return values need not be explained. It stops short of covering error/failure behavior, which is the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still reinforces the URL constraint (publicly reachable, completed/unencrypted HLS) and the async contract that frames all optional params, adding modest value beyond the schema's own field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb+resource: downloads a publicly reachable audio/video file or completed HLS stream and starts transcribing it. It also names the sibling it is not (start_upload for device 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.

Usage Guidelines5/5

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 media or finite HLS link they want transcribed') plus an explicit alternative for the device-file case ('use start_upload instead'), and it adds a when-not condition by limiting to completed, unencrypted HLS playlists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources