Skip to main content
Glama

get_subtitles

Finds and loads subtitles for the playing video from OpenSubtitles, choosing a hash-synced match when one exists, otherwise the most-downloaded subtitle for the title.

Instructions

Find and load subtitles for the playing video from OpenSubtitles, in one step. Picks the best match: a subtitle synced against this exact file if one exists (checked by file hash, so the timing is correct), otherwise the most-downloaded subtitle for the title. Prefer this over generate_subtitles when the video is a released film or show — a human-made subtitle is more accurate and arrives in a second rather than minutes. Requires the user's own OpenSubtitles API key in the opensubtitles_api_key setting; it fails with instructions if unset. Costs one of the user's limited daily downloads, so do not call it repeatedly.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_subtitles"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileNoVideo to match against. Defaults to the playing file.
loadNoLoad the subtitle into the player after downloading (default true)
queryNoSearch text. Omit to derive a title from the playing file's name.
languagesNoComma-separated OpenSubtitles language codes, e.g. "zh-CN,en". Defaults to the opensubtitles_languages setting, else English.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the matching strategy (file-hash sync check first, most-downloaded fallback), the prerequisite (user's own API key) and its explicit failure mode, and the quota cost per call. What it omits is what the call returns or what happens on a partial/failed match, which is a smaller gap for a no-output-schema tool but still a gap.

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?

Four sentences, front-loaded with the action and recommendation, then the matching logic, then prerequisites, then cost. No filler; each sentence supplies a decision-relevant fact.

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?

Covers prerequisite, failure behavior, cost, matching semantics and post-download loading for a 4-param, zero-annotation, no-output-schema tool. Only lightly incomplete: it never says what the tool returns or what a 'no match found' outcome looks like to the agent.

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 baseline is 3; the description earns one more by explaining what 'file' actually means operationally (hash-matched exact file so timing is correct) and how the language default chain resolves (setting, else English). It adds intent behind the parameters rather than repeating their 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 specific verb and resource ('Find and load subtitles for the playing video from OpenSubtitles, in one step') and immediately distinguishes itself from the sibling generate_subtitles, telling the agent when this tool is the better pick.

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 explicit when-to-use guidance ('Prefer this over generate_subtitles when the video is a released film or show') with the rationale (human-made, faster), plus an explicit anti-pattern ('do not call it repeatedly') tied to the daily download quota.

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

Deploy Server

Other Tools