Skip to main content
Glama

unspoken_detect

Destructive

Detect words a render never spoke by comparing its own transcription against timeline counts. Proposes seams and fragments where captions claim speech that is absent.

Instructions

Propose the words a render's own transcription says were never spoken.

Candidates come from two mechanisms and one witness decides both. A seam is where whisper read across a splice and invented a word; a fragment is where a cut left a sliver of a real one, which draws as a whole word on screen and is inaudible. The witness is the render: the candidate's word is counted in the timeline over a short window and in the render's own transcription over the same seconds, and it is proposed only where the timeline has more of them than the render heard. Counted rather than looked up because the inventions are function words — asking whether the render says "the" near here answers yes off the real one beside it.

apply=False by default, like reframe_detect: this changes what a caption says, and a wrong mark deletes a real word from every check proofcut has. Read the echoes first.

transcript_path takes an existing transcription of the render, which is what verify leaves in cache/verify/. Pass it explicitly — it is never found automatically, because a re-render under the same filename would otherwise be judged against the previous render's audio.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
padNoWiden the window each candidate is counted in, in seconds.
pathNoThe project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing.
applyNoMark the proposals. Off by default, like `reframe_detect`: a wrong mark deletes a real word from every check proofcut has, so read the echoes first.
modelNoThe whisper model to transcribe the render with, when no `transcript_path` is given.
renderYesThe rendered file to judge against — the witness. A word is proposed only where the timeline holds more of it over a span than the render's own transcription heard.
clip_idNoLimit the scan to one transcript.
languageNoForce a language code for that transcription.
transcript_pathNoAn existing transcription of `render`, which is what `verify` leaves in `cache/verify/`. It is never found automatically: a re-render under the same filename would otherwise be judged against the previous render's audio.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed27 schema fields changedv0.25.0
    • addedInput schema / properties / apply / description
      Added value: +"Mark the proposals. Off by default, like `reframe_detect`: a wrong mark deletes a real word from every check proofcut has, so read the echoes first."
    • removedInput schema / properties / apply / title
      Removed value: -"Apply"
    • removedInput schema / properties / clip_id / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / clip_id / description
      Added value: +"Limit the scan to one transcript."
    • removedInput schema / properties / clip_id / title
      Removed value: -"Clip Id"
    • addedInput schema / properties / clip_id / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / properties / language / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / language / description
      Added value: +"Force a language code for that transcription."
    • removedInput schema / properties / language / title
      Removed value: -"Language"
    • addedInput schema / properties / language / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / properties / model / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / model / description
      Added value: +"The whisper model to transcribe the render with, when no `transcript_path` is given."
    • removedInput schema / properties / model / title
      Removed value: -"Model"
    • addedInput schema / properties / model / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • addedInput schema / properties / pad / description
      Added value: +"Widen the window each candidate is counted in, in seconds."
    • removedInput schema / properties / pad / title
      Removed value: -"Pad"
    • removedInput schema / properties / path / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / path / description
      Added value: +"The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing."
    • removedInput schema / properties / path / title
      Removed value: -"Path"
    • addedInput schema / properties / path / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • addedInput schema / properties / render / description
      Added value: +"The rendered file to judge against — the witness. A word is proposed only where the timeline holds more of it over a span than the render's own transcription heard."
    • removedInput schema / properties / render / title
      Removed value: -"Render"
    • removedInput schema / properties / transcript_path / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / transcript_path / description
      Added value: +"An existing transcription of `render`, which is what `verify` leaves in `cache/verify/`. It is never found automatically: a re-render under the same filename would otherwise be judged against the previous render's audio."
    • removedInput schema / properties / transcript_path / title
      Removed value: -"Transcript Path"
    • addedInput schema / properties / transcript_path / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / title
      Removed value: -"unspoken_detectArguments"
  2. First observedv0.24.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag `destructiveHint: true`, and the description adds critical context beyond that: a wrong mark "deletes a real word from every check proofcut has" and therefore the agent should read echoes first. It also discloses that `transcript_path` is never found automatically to avoid judging a re-render by previous audio, which is exactly the kind of behavioral nuance annotations cannot convey.

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 long but well structured: purpose first, then mechanism, safety, and the key parameter caution. Every paragraph adds useful context, though the algorithm explanation (seams, fragments, counting rationale) is more elaborate than strictly necessary for invocation. It is not bloated, but it earns a 4 rather than a 5 because of that extra explanatory weight.

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 8-parameter tool with an output schema, the description covers purpose, algorithm, safety, prerequisites, and the one parameter behavior that would otherwise cause subtle errors. The output schema handles return-value details, and the schema covers the remaining parameters. Nothing essential is missing for an agent to call this correctly.

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

Parameters3/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 even without parameter details in the description. The description does reinforce the meaning of `apply`, `transcript_path`, and the counting window, but it mostly restates what the schema already says rather than adding new parameter-level semantics.

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: "Propose the words a render's own transcription says were never spoken." It then explains the two detection mechanisms (seam and fragment) and clearly separates proposing from applying by noting `apply=False` by default. This distinguishes it from manual siblings like `unspoken_add`/`unspoken_rm` without needing to inspect them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong operational guidance: pass `transcript_path` explicitly from `verify`'s cache, read the echoes first, and keep `apply=False` unless sure. It names `reframe_detect` as a sibling with the same safety default. It does not explicitly say when to prefer `unspoken_detect` over manual unspoken tools, but the propose-vs-apply distinction implies it.

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