proofcut

Overview Schema Source Related Servers Discussions Admin

resolve_phrase

Read-onlyIdempotent

Resolve a spoken phrase to a word range in a clip's transcript. Handles ambiguous matches via occurrence, falls back to fuzzy matching, and explains when it cannot pinpoint a match.

Instructions

Resolve a phrase to a word range against clip_id's transcript.

What phrase= on cue_add/cue_rm/unspoken_add/unspoken_rm/vo_extend/music/ locate calls internally, exposed on its own so a resolution — including its full ambiguity list — can be inspected without attempting a write. Companion to get_transcript with search=, which lists every match with no cursor/occurrence/fuzzy; this picks exactly one, or explains why it can't.

after skips matches at or before that word index (forward cursor, -1 means from the start). More than one exact match with no occurrence given fails with every candidate's word range and text — pass occurrence (1-based) to pick one, or narrow the phrase. Zero exact matches falls back to a fuzzy match (fuzzy=False to refuse instead) — ratio is set only on a fuzzy hit, never disguised as exact. Read-only.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	No	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.
`after`	No	A forward cursor over a phrase's matches: any match at or before this word index is skipped. -1, the default, means from the start.
`fuzzy`	No	Fall back to a fuzzy match when nothing matches exactly. A fuzzy hit sets `ratio` and is never reported as an exact one; `false` refuses instead.
`phrase`	Yes	The words to find, as they were spoken.
`clip_id`	Yes	The transcript to resolve against.
`occurrence`	No	Disambiguate a phrase by count when it matches more than once, 1-based in transcript order among the matches after `after`: 1 is the first, 2 the second. Unset, an ambiguous phrase is refused — listing every candidate's range and text — rather than guessed at.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.25.0Sep 16, 2026

addedInput schema / properties / after / description

Added value: +"A forward cursor over a phrase's matches: any match at or before this word index is skipped. -1, the default, means from the start."

removedInput schema / properties / after / title
```
Removed value: -"After"
```
addedInput schema / properties / clip_id / description
```
Added value: +"The transcript to resolve against."
```
removedInput schema / properties / clip_id / title
```
Removed value: -"Clip Id"
```

addedInput schema / properties / fuzzy / description

Added value: +"Fall back to a fuzzy match when nothing matches exactly. A fuzzy hit sets `ratio` and is never reported as an exact one; `false` refuses instead."

removedInput schema / properties / fuzzy / title
```
Removed value: -"Fuzzy"
```

removedInput schema / properties / occurrence / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / occurrence / description

Added value: +"Disambiguate a phrase by count when it matches more than once, **1-based** in transcript order among the matches after `after`: 1 is the first, 2 the second. Unset, an ambiguous phrase is refused — listing every candidate's range and text — rather than guessed at."

removedInput schema / properties / occurrence / title
```
Removed value: -"Occurrence"
```
addedInput schema / properties / occurrence / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

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 / phrase / description

Added value: +"The words to find, as they were spoken."

removedInput schema / properties / phrase / title
```
Removed value: -"Phrase"
```

removedInput schema / title

Removed value: -"resolve_phraseArguments"

First observedv0.24.0Sep 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses important edge-case behavior: ambiguous matches fail and list candidates, fuzzy fallback sets ratio and is never disguised as exact, and the after cursor skips matches at or before a word index. The explicit 'Read-only' statement is consistent with 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 purpose and is dense with useful information, but it runs to four paragraphs and slightly repeats details already present in the input schema. Still, each paragraph contributes real behavioral or usage context, so it remains tight for the tool's complexity.

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 6-parameter resolver with ambiguity handling, fuzzy fallback, cursor semantics, and a read-only inspection role, the description covers all critical behavior an agent needs to invoke it correctly. An output schema exists, so not detailing return values is acceptable.

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 description coverage is 100%, and the parameter descriptions already explain after, occurrence, fuzzy, clip_id, phrase, and path in detail. The tool description mostly restates key semantics rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.

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 states a specific verb, resource, and result: 'Resolve a phrase to a word range against clip_id's transcript.' It further distinguishes itself from get_transcript and explains its role as the internal resolver behind phrase= on several mutation tools, so an agent can tell exactly what it does.

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?

The description explicitly contrasts this tool with get_transcript's search= mode: that tool lists every match, while this one picks exactly one or explains why it cannot. It also says it is exposed for inspecting a resolution without attempting a write, giving a clear when-to-use signal versus the mutation tools that call phrase= internally.

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

Deploy Server