searchts

Overview Schema Source Related Servers Discussions Admin

transcribe

Extract spoken words from captionless player pages or local audio/video files, using existing subtitles first and Whisper as the fallback.

Instructions

Read the spoken words when read_url says a player page has no captions, or transcribe a local audio/video file. A YouTube watch URL, a TikTok video, an Instagram reel, a v.redd.it file, or an X post that has a video is a player page: read_url returns its captions, or an error that names this tool for the audio. Subtitles-first: existing captions via yt-dlp need no API key; otherwise Whisper (Groq/OpenAI if configured, else keyless local whisper.cpp, bundled; provider=local-fw forces the temporary faster-whisper fallback. The PyPI wheel is CPU-only today; GPU-enabled wheels are a follow-up. prefer_subtitles defaults true; set false to force audio. Local options: model (small default, turbo, base), hint (names or words the audio contains, e.g. from the page title), translate (to English; not with turbo). The local model is downloaded once: without yes=true the call returns an Error naming its size and source; ask the user, then call again with yes=true. cookies_from_browser is opt-in (chrome/firefox/…) and uses THIS machine's browser cookies; read_url does not copy them. The compressed audio (never the video) is kept for 24 hours in ~/.searchts/cache/audio, so a repeat of the same URL skips the download; pass fresh=true to download again, and the receipt's audio_cache says hit, miss or off (off for a local file, cookies, or caching turned off). Returns the transcript text, then a transcribed_by: JSON line (source, engine, model, device, detected language, audio_cache). Missing-model consent is returned as structured JSON with the exact yes=true approval; other failures use an 'Error: ...' string. Update check: when a newer release exists, a successful result also carries 'update_available' plus, at most once per 24 hours, one line telling the agent. The check is one GET to the GitHub latest release of capad-xyz/searchts, at most once per 24 hours, cached in ~/.searchts/update-check.json, with a searchts User-Agent and nothing about the user. Nothing is installed or changed. SEARCHTS_NO_UPDATE_CHECK=1 turns the check and the note off.

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": {
      "source": "<source>"
    },
    "name": "transcribe"
  }
}

Input Schema

Name	Required	Default
`yes`	No
`hint`	No
`fresh`	No
`model`	No
`source`	Yes
`provider`	No	auto
`translate`	No
`prefer_subtitles`	No
`cookies_from_browser`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.25.1Oct 31, 2026

addedInput schema / properties / fresh

Added value: +{
+  "default": false,
+  "title": "Fresh",
+  "type": "boolean"
+}

addedInput schema / properties / hint

Added value: +{
+  "default": "",
+  "title": "Hint",
+  "type": "string"
+}

addedInput schema / properties / model

Added value: +{
+  "default": "",
+  "title": "Model",
+  "type": "string"
+}

addedInput schema / properties / translate

Added value: +{
+  "default": false,
+  "title": "Translate",
+  "type": "boolean"
+}

addedInput schema / properties / yes

Added value: +{
+  "default": false,
+  "title": "Yes",
+  "type": "boolean"
+}

Addedv0.10.1Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/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 so: subtitles-first ordering, which engines need API keys vs the keyless local fallback, provider=local-fw forcing faster-whisper, the missing-model consent flow with structured JSON, 24-hour audio caching in ~/.searchts/cache/audio with hit/miss/off receipts, and the once-per-24h GitHub update check that installs nothing and is disabled by SEARCHTS_NO_UPDATE_CHECK=1. These are exactly the non-obvious behaviors an agent cannot infer from 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.

Conciseness4/5

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

Front-loaded with the routing condition and source types, then grouped by concern (engines, local options, consent, caching, returns, update check). It is dense but earns most of its length; the one clear non-earner is the packaging aside about CPU-only PyPI wheels and future GPU wheels, which does not inform a tool-selection or invocation decision.

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

Completeness5/5

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

An output schema exists, yet the description still supplies the two return shapes that matter for agent control flow: the missing-model consent JSON requiring an exact yes=true approval versus generic 'Error: ...' strings, plus the trailing `transcribed_by:` line and the optional update_available field. Nothing needed to call this correctly, including the consent retry loop, is missing.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it covers essentially all nine parameters: source (by enumerated URL/file types), hint (names or words in the audio, e.g. from the page title), model (small default, turbo, base), translate (to English, incompatible with turbo), provider (local-fw), fresh (re-download), yes (consent), cookies_from_browser (browser cookie jars on this machine), prefer_subtitles (default true). It even flags the non-obvious constraint that translate cannot be combined with turbo.

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?

Opens with a concrete verb+resource ('Read the spoken words ... or transcribe a local audio/video file') and immediately names the sibling that routes to it (read_url). The enumerated source types (YouTube watch URL, TikTok, Instagram reel, v.redd.it, X post with video, local file) make the tool's domain unmistakable.

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?

Explicit entry condition: use this when read_url reports a player page has no captions and returns an error naming this tool. It also states the exclusions and overrides — prefer_subtitles defaults true and must be set false to force audio, cookies_from_browser is opt-in, and yes=true is required only after the user approves the model download.

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

Deploy Server