talkthrough-mcp

Overview Schema Source Related Servers Discussions Admin

label_speakers

Idempotent

Assign verified human-readable names to anonymous speaker labels on a diarized job, with optional evidence to document why each mapping is trusted.

Instructions

Persist VERIFIED human-readable names for anonymous S1/S2/… labels on one diarized job. labels is a patch: a 1-100 character name saves it; null or blank removes it. Optional evidence (max 500 characters per label) records why the mapping is trusted. Raw labels remain canonical in JSON; names appear separately and in text/SRT display. The write is atomic, locked, local, and idempotent. OCR name_candidates are raw hints only and are never saved automatically. A relabelled job can carry pending-review names with source-roster anchors. For a label still in the roster, an explicit patch confirms, replaces, or removes only that entry. For a stale pending label, only an explicit null removes its name, evidence, and context. When NOT to use: before diarization, or when a name is only a guess without human/screen evidence. Examples:

label_speakers(job_id="...", labels={"S1":"Vera"}) — save one verified mapping
label_speakers(job_id="...", labels={"S1":"Vera","S2":"Tom"}) — patch several labels
save evidence: label_speakers(job_id="...", labels={"S1":"Vera"}, evidence={"S1":"intro at 1200ms"})
screen name plate confirms S2 → save the name and cite its frame timestamp in evidence
label_speakers(job_id="...", labels={"S2":null}) — remove S2's name and evidence together
label_speakers(job_id="...", labels={"S2":" "}) — blank also removes the mapping
named S1, new proof → label_speakers(job_id="...", labels={}, evidence={"S1":"title card at 0ms"})
two Alexanders may map to S2 and S5 — duplicate names are allowed and search covers both
response roster carries speaker_name beside label; raw S labels are never replaced
name_candidates may be UI text or another person's name → inspect frames before deciding
unknown label or a name over 100 characters → error lists the valid roster labels
fresh session: get_transcript returns saved names; do not infer the mapping again
stale pending S3 → labels={"S3":null}; never assign a name while S3 is outside the roster
anti-example: uncertain identity → keep S anonymous until evidence verifies the name

Input Schema

TableJSON Schema

Name	Required	Description	Default
`job_id`	Yes
`labels`	Yes
`evidence`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.0Aug 29, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description discloses atomicity, locking, locality, and idempotency, plus null/blank removal semantics, duplicate-name allowance, and that name_candidates are never persisted automatically. This goes well beyond the annotations' idempotentHint and adds meaningful operational context without contradicting the annotations.

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 the core contract and includes a dedicated 'When NOT to use' section, but the long example list contains some redundancy (e.g., null and blank removal are both demonstrated). Still, the length is largely warranted by the tool's edge-case-heavy behavior.

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?

The description covers success behavior, error conditions, the response roster carrying speaker_name, interaction with stale labels, and the relationship to get_transcript and name_candidates. With the output schema present, nothing an agent needs to call this safely 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%, but the description fully compensates: labels is defined as a patch where 1-100 character names save and null/blank removes, evidence is capped at 500 characters per label, and job_id refers to a diarized job. Concrete examples map each parameter to realistic calls.

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 opening sentence names a precise verb and resource: 'Persist VERIFIED human-readable names for anonymous S1/S2/... labels on one diarized job.' It also distinguishes itself from get_transcript by clarifying names are a separate layer from raw labels, and the 'When NOT to use' section reinforces scope.

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: before diarization or when the name is only a guess without human/screen evidence. It also points to get_transcript for reading already-saved names and warns against assigning names while a label is outside the roster.

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

Deploy Server