talkthrough-mcp

Overview Schema Source Related Servers Discussions Admin

process_media

Idempotent

Ingest a local video or audio file and make it queryable: transcribe speech, extract keyframes, OCR on-screen text, and optionally identify speakers. Returns a summary with job ID for retrieval.

Instructions

Ingest a LOCAL video or audio file and make it queryable: validates the file, transcribes speech locally (whisper), extracts scene-change keyframes, OCRs on-screen text, resolves the wall-clock start time, and (opt-in) labels who said what via local speaker diarization. Returns a compact summary (job_id, media info, wall_clock, transcript preview, speaker roster when diarized) — full data stays on disk and is served lazily by the other tools. Idempotent by content hash: re-calling on an already-processed file returns instantly. For MULTI-PERSON recordings (meetings, interviews, calls) diarize=true is part of a proper analysis — pass it even when the user only asks for a summary. num_speakers is a target the clusterer may not reach, not a constraint — the payload says when a re-run changed nothing (labels_changed). If an amend changes the labels, verified names become pending-review evidence rather than active identities, with old-roster anchors for re-checking. Current pending labels can be confirmed/replaced/removed; stale labels can only be removed with an explicit null patch. Full force reprocessing of a job with saved or pending identities requires diarize=true and preserves every old identity as pending review against the rebuilt roster; without diarization it refuses before changing the stored job. When NOT to use: to re-fetch data you already processed (use the retrieval tools), or for URLs — local file paths only; a public video/audio URL goes to process_url. Examples:

process_media(path="/Users/sam/Desktop/bug-repro.mov") — narrated screencast, defaults are right
meetings: model="large-v3-turbo" + vocabulary=<attendees, terms> + num_speakers=N — turbo's extra cost is trivial
process_media(path="/tmp/standup.m4a") — audio-only: transcript tools work, frame tools will error
process_media(path="/rec/panel.mov", diarize=true, num_speakers=4) — headcount known? ALWAYS pass it: best accuracy
relabel amend → names become pending with old anchors; stale labels are removable only with null
error mentions [diarization] → run uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization]"
know the attendees? process_media(path=..., vocabulary="Anastasia, Evgenii, OKR") — names+jargon survive STT
user: "analyze/summarize this meeting" → include diarize=true — speaker structure is not optional extra credit
noisy threshold roster (clusters ≫ people)? ASK your user for the real headcount, then re-run with num_speakers=N
cap_hit or sampling_interval_s in summary → for slide hunts raise TALKTHROUGH_MAX_FRAMES or use extract_frame
summary shows wall_clock=null → ask when recording started, re-call with recorded_at=... and force=true
transcript garbled or language_probability low → re-call with model="large-v3-turbo" (or language="ru") + force=true
after success, do NOT dump everything — continue with get_transcript / get_moment / search on the job_id
anti-example: frames from an already-processed job → get_frames(job_id=...), never process_media again
named job + force=true → include diarize=true; old identities return as pending review, never silently vanish

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes
`force`	No
`model`	No
`diarize`	No
`language`	No
`vocabulary`	No
`recorded_at`	No
`num_speakers`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.4Aug 3, 2026
Removedv0.2.0Jul 17, 2026
First observedv0.1.0Jul 11, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description goes far beyond the annotations: it discloses idempotency by content hash, lazy serving from disk, refusal to re-process saved identities without diarize=true, pending-review label behavior, null-patch removal for stale labels, and failure signals like wall_clock=null or cap_hit. These behavioral traits are not visible in the annotations and are critical for correct invocation.

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?

The description is front-loaded with a dense summary, then organized into not-to-use guidance, examples, and troubleshooting. It is long, but the length is mostly earned given 0% schema coverage and the tool's complex diarization/identity edge cases; a slightly tighter arrangement would improve conciseness.

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?

For a complex ingestion tool with 8 parameters, no schema descriptions, and nuanced behavioral rules, the description is remarkably complete. It covers inputs, outputs, failure modes, parameter semantics, follow-up actions, environment setup for diarization, and explicit when-not-to-use cases. An agent has everything needed to call this tool correctly in a wide range of scenarios.

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 description coverage is 0%, so the description carries the full burden, and it delivers. It adds real meaning to path (local only), diarize (required for multi-person), num_speakers (a target, not a constraint), model and language (when to upgrade/re-run), vocabulary (names+jargon survive STT), recorded_at (needed when wall_clock=null), and force (required alongside diarize for named jobs). Every parameter is given operational context beyond its bare schema type.

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?

The description opens with a specific verb and resource: ingest a LOCAL video or audio file and make it queryable, then enumerates the concrete pipeline (validate, transcribe, keyframes, OCR, wall-clock, diarization). It clearly differentiates itself from siblings like process_url and the retrieval tools, so an agent can select it without ambiguity.

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?

It explicitly states when NOT to use the tool: re-fetching processed data should use retrieval tools, and URLs belong to process_url. Numerous examples map user intents (meeting summaries, audio-only files, known headcounts, re-processing) to the correct parameters, including an anti-example that warns against re-processing already-processed jobs.

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

Deploy Server