A
licenseNot graded
qualityD
maintenanceEnables AI agents to edit videos through natural language, providing tools for timeline editing, audio management, rendering, and more.
2
MIT
splicedeck
splicedeck
Un editor de vídeo que un agente de IA maneja, ejecutándose en tu propia máquina.
Una sola llamada arregla un corte en una plantilla: gráficos animados, superposiciones, subtítulos y una cuadrícula de ritmo para cortar en ella. Una sola pasada sobre una fuente te da tanto un máster de formato largo limpio como clips verticales. Y recuerda cómo le gusta ser cortado a cada cliente, canal o programa, así que el siguiente montaje empieza donde terminó el anterior.
No hay línea de tiempo que arrastrar ni cuenta que crear. No se sube nada.
Estado: el pipeline se ejecuta de principio a fin, y la memoria llega al corte
Una fuente se convierte en un archivo entregado hoy. Medido en la máquina de referencia (Windows 11, Python 3.13, ffmpeg 8.1.2) contra un
.movreal de 223 MB:inspect 2.6 s draft 27 ms splice 27 ms verify 42 ms deliver 157 s -> 1920×1080 h264 + aac, -23.0 LUFS, decodes clean
python -m pytestreporta 1425 aprobados, 2 omitidos en unos cuatro minutos. Treinta y un verbos llegan a la CLI y dieciocho de ellos llegan a un servidor MCP, ambos generados desde una misma tabla para que no se desvíen.Una característica destacada no funciona todavía. Cortar citando necesita un binario de habla que ningún manifiesto puede obtener actualmente. Lea Qué no funciona antes de planificar en función de ello.
Instalar
Necesitas Python 3.12 o superior y ffmpeg 8.x en tu PATH. splicedeck no instala ni
incluye ffmpeg, y docs/first-run.md §4 explica por qué eso es
intencionado.
El script de instalación pregunta dónde va el espacio de trabajo, ofrece instalar ffmpeg después de mostrarte el comando exacto, crea todo y escribe una configuración MCP:
curl -fsSLO https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.sh
less install.sh && bash install.shirm https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.ps1 -OutFile install.ps1
notepad install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1Léelo antes de ejecutarlo. Un comando curl | bash en una línea sería una mala publicidad para un
proyecto cuyo README trata en gran parte sobre un modelo de amenaza.
Si prefieres hacerlo tú mismo, o quieres las pruebas:
uv tool install splicedeck # or: pipx install splicedeck
git clone https://github.com/ihuzaifashoukat/splicedeck.git && cd splicedeck
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]" # Windows
.venv/bin/python -m pip install -e ".[dev]" # macOS, LinuxAún no en PyPI. No hay ninguna versión, por lo que uv tool install splicedeck dará 404 hasta
que se suba la primera etiqueta. Hasta entonces usa el script, un clon, o
uv tool install "git+https://github.com/ihuzaifashoukat/splicedeck.git".
docs/install.md tiene todas las rutas, los comandos de ffmpeg por plataforma,
las variables de entorno, y un prompt que puedes pegar en un agente de IA para que instale
y configure splicedeck por ti.
Related MCP server: ViralSpin MCP
Probarlo
La raíz del espacio de trabajo es cualquier directorio en el que ejecutes, y spd init crea uno:
mkdir my-edit && cd my-edit
spd init # bookmarks/ casebook/ elements/ ledger/ media/ profiles/ templates/
mkdir -p casebook/parties/demo
spd ready # what is present, and what each gap blocksinit nunca sobrescribe. Volver a ejecutarlo después de haber editado un perfil completa lo que
falta y deja tus ediciones intactas. Los archivos que escribe son idénticos byte a byte
a los que envía este repositorio, y python -m checks.starter --check lo exige.
Luego coloca tu material grabado en media/ y corta:
spd inspect --path media/your-file.mov # mints a source handle
spd draft --party demo --source s1 --bookmark baseline --profile wide-1080
spd apply --sheet c1 --template clean-master # overlays, motion, beat grid
spd splice --sheet c1 --source a --in_ticks 0 --out_ticks 900000 \
--source_in_ticks 0 --cause manual
spd verify --sheet c1
spd deliver --sheet c1Las fuentes deben estar dentro del espacio de trabajo. Una ruta con una letra de unidad es rechazada como
PATH_OUTSIDE_WORKSPACE antes de leer nada.
Una "party" (sesión/proyecto) es creada por un humano, a mano, a propósito. draft rechaza UNKNOWN_PARTY
hasta que exista casebook/parties/<nombre>/.
Para manejarlo desde un asistente compatible con MCP, registra el servidor:
{"mcpServers": {"splicedeck": {
"command": "C:\\src\\splicedeck\\.venv\\Scripts\\python.exe",
"args": ["-m", "splicedeck.surface.mcp"],
"cwd": "C:\\src\\splicedeck"}}}cwd debe ser el espacio de trabajo, porque la raíz del espacio de trabajo es el directorio de trabajo y
nada más lo descubre. python -m splicedeck.surface.mcp --tools imprime la
lista de herramientas generada y sale, que es como se distingue un servidor roto de una configuración de host rota.
docs/mcp.md es la guía completa.
Plantillas: el aspecto en una llamada
apply viste una hoja de corte en una plantilla con nombre. Coloca las superposiciones, escribe la
cuadrícula de ritmo contra la que el agente luego corta, y registra en la hoja qué plantilla usó.
Cuatro vienen incluidas hoy:
Plantilla | Qué es |
| Un máster tranquilo de orador con un único tercio inferior y sin cuadrícula de ritmo |
| Un vertical de corte rápido: tres espacios de ritmo con un acento pulsante en cada uno |
| Un aspecto promocional: tarjetas de introducción y conclusión a sangre alrededor de dos espacios de ritmo |
| Una pequeña marca en pantalla y nada más |
Las superposiciones de una plantilla se animan cuando el nivel de movimiento opcional está instalado, y caen
en una impresión estática cuando no lo está. Seis composiciones animadas vienen incluidas en
scenes/, escritas para este proyecto y licenciadas con él.
Los espacios se aplican. verify se niega a pasar una hoja con un espacio sin rellenar, y un corte
que caiga fuera de la tolerancia de un espacio es rechazado como SLOT_TOO_TIGHT con los límites legales
más cercanos devueltos como llamadas listas para enviar. Eso es lo que permite a un agente alcanzar un ritmo
que no puede ver.
Puedes escribir las tuyas propias. spd compose --kind template valida y escribe una
plantilla o tarjeta de elemento creada a mano. Es deliberadamente solo CLI: el servidor MCP
no puede escribir en templates/, y docs/templates.md §4 explica el
razonamiento en lugar de tratarlo como un descuido.
Por qué memoria
Un montaje son mil pequeños juicios y casi todos se repiten. Cuánto tiempo mantener después de un remate. Si el relleno de este orador es ruido o personalidad. Qué tan grandes deben ser los subtítulos en un teléfono a la distancia del brazo. Una herramienta sin estado te obliga a volver a proporcionar esa información cada sesión, por lo que la "edición con IA" tan a menudo produce algo técnicamente correcto y tonalmente incorrecto.
Aquí, una decisión que tomas una vez se registra y reutiliza:
subtitle.size_px = 74
when {surface: vertical, frame: 1080x1920}
set by a render you shipped and kept, 2026-08-02
before 66Ese registro vive en tu repositorio como texto revisable. Puedes leer el diff, corregir
una entrada incorrecta editando una línea, y git revert un cambio que empeoró los montajes. Es
un registro de cambios de comportamiento, mantenido en el mismo lugar que todo lo demás que versionas.
Dos reglas lo mantienen fiable:
Nada duradero es escrito por el modelo. Un registro describe algo que un humano hizo: envió un render y lo mantuvo, restauró un momento que el corte eliminó. El agente puede señalar lo que sucedió; no puede componer lo que se recuerda.
Cada escritura pasa por una puerta humana. Ninguna preferencia se aprende en silencio.
Ese bucle se ejecuta hoy. spd set, ship, keep, restore y discard añaden actos al
libro mayor encadenado por hash de una party y preparan una propuesta a partir de cada uno; un acto no puede
ser añadido a una cadena que no se verifica. spd review entonces pide el valor a ciegas,
mostrando los límites y el corte enviado pero nunca el número, y una respuesta coincidente
se convierte en un caso sellado y un findings.lock.txt regenerado. El siguiente draft resuelve
contra él: el marcador abre la configuración, el libro de casos anula aquellos que un humano
estableció, y la hoja registra qué bloqueo leyó.
Local primero, y completo
Un clon nuevo sin claves de API y sin cuenta en la nube produce un archivo terminado y entregado en tu propia máquina. Ese es el punto de partida, no un modo degradado.
Los servicios en la nube se pueden activar donde realmente ayuden, como una API de habla alojada para audio difícil o diarización, pero nada se vuelve obligatorio y ningún entregable depende de uno. ffmpeg hace el trabajo como un proceso hijo. Nunca se vende y nunca se enlaza.
El proyecto también se niega a adivinar sobre tu hardware. La compatibilidad con codificadores se demuestra
codificando de prueba en lugar de leer una lista de características, porque las listas de características mienten. En la máquina de
desarrollo ffmpeg -encoders anuncia un codificador NVIDIA que falla en
tiempo de ejecución, mientras que el Intel que realmente funciona no se menciona en ninguna guía.
Qué funciona
Una pasada de análisis, dos entregables. La transcripción y el análisis se ejecutan una vez por fuente. El máster de formato largo y los clips verticales leen los mismos resultados.
Corte preciso a fotograma sin desviación de audio. El audio permanece en PCM hasta el mux y se codifica una vez. Las muestras entregadas son idénticas byte a byte a un ensamblaje de referencia construido en Python sobre 45 y 120 uniones. Medido, no afirmado.
Plantillas y movimiento en una sola llamada, con una cuadrícula de ritmo contra la que el agente corta y un respaldo estático cuando el nivel de movimiento está ausente.
Subtítulos que siguen siendo legibles. Los límites mínimos de tamaño y contraste son aplicados por el renderizador, y el texto que caería debajo de la propia interfaz de una plataforma se rechaza en lugar de dibujarse. Los glifos se forman y rasterizan mediante un analizador TrueType de stdlib puro, por lo que las impresiones son byte-reproducibles y se confirman como doradas.
Encuadre vertical que admite incertidumbre. Cuando el sujeto no puede ser rastreado con confianza, declina autoencuadrar y dice por qué. Un recorte erróneo con confianza es peor que una negativa honesta, porque nadie revisa el que parecía correcto.
Derechos que se sostienen. La música, los efectos y el material de archivo llevan un registro de dónde vinieron y qué permiten los términos. Una entrega se niega a ejecutarse si algún activo carece de uno.
Negativas tipadas que llevan su propia corrección. Una negativa llega con
retry_with, una lista de llamadas listas para enviar. Hay 102 códigos, cada uno con un sitio de construcción y una prueba que demuestra que es alcanzable.
Qué no funciona
Dicho claramente, porque una sección de estado que omite esto es la razón por la que la última fue inútil.
No funciona | Por qué | Bloquea |
Cortar citando |
|
|
Seguimiento de sujeto por modelo | Ningún detector está fijado o incluido ( |
|
Cancelar desde un host MCP | El bucle stdio es de un solo hilo, por lo que nada puede llegar durante un |
|
CHANGELOG.md lleva la misma lista, y se espera que ambas se mantengan sincronizadas.
Dos niveles por debajo del nivel de modelo sí funcionan. subject: "centre" es geométrico y no necesita
nada. SPD_SIGHT_LOCATOR=reduce selecciona un localizador libre de pesos que encuentra el sujeto
mediante sustracción de fondo de mediana temporal en Python stdlib puro, sin numpy y sin ninguna extensión compilada
.
Verificado contra un detector de rostros en el máster de referencia, la mediana de ese localizador coincidió dentro
del 0.1% del ancho del fotograma. En el mismo metraje luego reportó certeza 0.26 y no ajustó
ninguna trayectoria, porque un orador que apenas se mueve contra un fondo estático no deja nada
para que la sustracción de fondo se aferre. Ambas son la respuesta correcta: la aritmética es
sólida, y el límite honesto de un nivel libre de pesos es un agujero en lugar de una suposición
centrada (docs/framing.md §7). El metraje con un sujeto en movimiento se rastrea bien.
Cómo lo manejas
A través de un servidor MCP y Skills, para que cualquier asistente compatible con MCP pueda usarlo, además de una CLI
que expone exactamente los mismos verbos. Ambas superficies se generan a partir de
splicedeck/surface/verbs.py, y python -m checks.golden --check hace fallar la compilación si
se desvían.
El servidor habla cinco revisiones de protocolo, 2024-11-05 a 2026-07-28, y
responde tanto al protocolo de apretón de manos initialize como a server/discover.
Los fallos están tipificados. Una negativa lleva su propia corrección como llamadas listas para enviar en lugar de prosa que un agente tenga que interpretar, por lo que la recuperación es de un turno:
{"ok": false, "verb": "draft", "refused": "BOOKMARK_UNKNOWN",
"plain": "No bookmark by that name is shipped.",
"needs_human": false,
"retry_with": [{"verb": "draft", "args": {"bookmark": "baseline", "party": "demo",
"profile": "wide-1080", "situation": "default", "source": "s1"}}]}Habilidades
Cuatro habilidades enseñan a un agente el orden de los verbos, las trampas entre verbos y cómo convertir una
negativa en la siguiente llamada correcta. Se encuentran en
.claude/skills/, y un clon las recoge sin necesidad de instalación alguna.
Habilidad | Se activa cuando |
| Convertir un código fuente en un archivo entregado |
| Tallar un clip 9:16 y mantener el sujeto en el encuadre |
| Cualquier |
| Editar este código base, o cuando dos documentos discrepan |
Este repositorio es también un plugin de Claude Code y su propio mercado:
claude plugin marketplace add ihuzaifashoukat/splicedeck
claude plugin install splicedeck@splicedeckO instala las habilidades en cualquiera de los agentes que soporta la CLI skills, incluyendo
Codex, Cursor, OpenCode, Antigravity, Cline, Gemini CLI, Zed y Windsurf:
npx skills add ihuzaifashoukat/splicedeck # add --list to look firstAmbas rutas envían solo las habilidades. No registran el servidor MCP, porque el
servidor necesita una ruta absoluta del intérprete y un cwd que ni un plugin ni un instalador
de habilidades pueden conocer. install.sh lo escribe por ti, y
docs/mcp.md lo tiene a mano.
Cualquier otro runtime de agente lee AGENTS.md.
Diseño
La especificación está escrita antes que el código, deliberadamente.
Documento | Lo que establece |
El contrato bajo el que trabaja cada colaborador y agente | |
El mapa: runtimes, paquetes, flujo de datos | |
Desde el clon hasta el archivo entregado, y las trampas en Windows | |
Cada ruta de instalación, y un prompt para un agente de IA | |
Manejar splicedeck desde un asistente | |
El artefacto central: con temporización entera, diferenciable, legible por humanos | |
Plantillas, ranuras, y qué hacen | |
Cómo se almacena, resuelve y controla la memoria | |
El modelo de amenazas, y por qué la memoria es una superficie de ataque | |
Estilos, y los ejes que son puntos en ellos | |
La tabla de verbos y el catálogo de negativas | |
Las áreas de funcionalidad, y qué tiene que demostrar cada una |
La memoria persistente en un agente es una superficie de seguridad, no solo una funcionalidad. Cualquier cosa que un atacante
pueda escribir en ella sobrevive a la conversación que la plantó. Si lees un documento, lee
docs/security.md.
No objetivos
Montar una película a partir de múltiples fuentes. Generar vídeo o música. Una interfaz gráfica de línea de tiempo. Colaboración en tiempo real. Un servicio alojado. Elegir automáticamente qué momentos se convierten en clips, ya que presenta candidatos y espera a una persona.
Requisitos
Python 3.12 o más reciente, y ffmpeg 8.x en tu PATH. No se utiliza ninguna extensión compilada de Python en ninguna ruta predeterminada, por lo que no hay paso de compilación ni runtime de plataforma que instalar primero.
Windows, macOS y Linux; CI cubre Ubuntu y Windows, y macOS no está probado por máquina.
El nivel de movimiento adicionalmente necesita Node y un npm install dentro de scenes/. Es
opcional, y una entrega sin él recurre a marcas fijas.
Contribuciones
Las incidencias y las críticas de diseño son bienvenidas. CONTRIBUTING.md es la
puerta de entrada: configuración, las comprobaciones a ejecutar, cómo añadir un verbo o un código de negativa, y las
cosas que hacen que una solicitud de extracción sea rechazada independientemente de su mérito. Lee
AGENTS.md primero. Las doce reglas estrictas son fundamentales, y un cambio
que rompa una se rechaza solo por esa base.
Al participar, aceptas el Código de Conducta.
Seguridad
Por favor, no abras una incidencia pública para una vulnerabilidad. SECURITY.md tiene
la ruta de notificación y qué está en alcance.
Licencia
Apache-2.0. Copyright 2026 Huzaifa Shoukat.
Available Tools
18 toolsapplyC
Dress a cut sheet in a named template: its overlays and its beat grid.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| sheet | Yes | A cut sheet handle. | |
| dry_run | No | Return the calls this would make instead of making them. | |
| template | Yes | A template id under templates/. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full load for behavioral transparency. It only states the action without disclosing side effects, destructive nature, idempotency behavior, permissions, or what happens to existing data. The mention of 'dress' implies modification but lacks necessary detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 13 words that efficiently conveys the core action and scope. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, yet the description omits operational details such as return values, error conditions, or the effect of the idempotency key. The agent lacks sufficient context to understand the full lifecycle of using this tool, making it incomplete for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining that the template applies overlays and beat grid to the sheet. This contextualizes the 'template' and 'sheet' parameters beyond their raw definitions, despite the schema already having 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies a named template to a cut sheet, specifying that it affects overlays and beat grid. The verb 'dress' is domain-specific but still conveys the intended action on a specific resource, distinguishing it from sibling tools like 'draft' or 'splice'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, contraindications, or typical workflows. Without any usage context, an agent has no basis to decide between 'apply' and other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancelC
Stop a running job and everything it started.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job | Yes | A job handle. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states the tool stops 'everything it started', hinting at cascading effects, but does not mention whether this is irreversible, whether it requires special permissions, or what happens to dependent processes. The serious consequence of destruction is implied but not explicitly flagged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, minimal words, no redundancy. Every word is necessary and information-dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, irreversible action on a running resource, the description should explicitly mention return behavior (e.g., success/error feedback), side effects, and safety considerations. With no output schema, the agent is left without important context. The tool's simplicity suggests it could be concise while still warning about consequences.
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%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema provides (e.g., what a valid job handle looks like, format, or where to obtain it).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Stop') and specific resource ('a running job'), and adds scope ('and everything it started'). While it does not explicitly distinguish itself from siblings, its action is distinct enough to infer purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., when to cancel vs stop via inspect, or cleanup implications). The description lacks any context about prerequisites (e.g., job must be running) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
captionC
Build caption imprints for a cut sheet from the source's words.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| sheet | Yes | A cut sheet handle. | |
| style | No | A style slot name. null uses the settled finding. | |
| motion | No | Which caption renderer to use. 'still' draws a static block per caption; 'scene' highlights each word as it is spoken. | still |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not mention side effects, idempotency (despite the 'key' parameter), destructive potential, or auth requirements. The phrase 'Build caption imprints' hints at creation but lacks depth on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero waste. Every word contributes meaning, and it efficiently conveys the core purpose without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description omits crucial details such as the meaning of 'caption imprints', the behavior of the 'motion' enum, or the format of the result. The agent would lack sufficient context to use the tool confidently.
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%, so the baseline is 3. The description adds modest context by linking 'cut sheet' to the required 'sheet' parameter and 'source's words' to the tool's input, but it does not elaborate on the 'key', 'style', or 'motion' parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Build') and resource ('caption imprints for a cut sheet from the source's words'), distinguishing it from sibling tools like 'preview' or 'watch' by focusing on imprint creation rather than viewing. However, the phrase 'caption imprints' is somewhat jargon-heavy and could be more universally understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'preview', 'hear', 'draft'). It neither specifies prerequisites nor warns against misuse, leaving the agent without context for choosing 'caption' over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
carveC
Cut a span of a master cut sheet out into its own clip sheet at a different delivery shape.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| sheet | Yes | The master cut sheet handle to carve from. | |
| profile | Yes | The clip's delivery profile name. | |
| subject | No | Which cached framing path to write into the clip: largest, centre, or none. | largest |
| in_ticks | Yes | First deliverable tick of the master kept. | |
| out_ticks | Yes | First deliverable tick of the master not kept. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only describes the high-level operation without mentioning side effects, idempotency behavior, or what happens to the original master sheet. The schema includes a 'key' parameter for idempotency, but the description ignores this, leaving the agent uninformed about repeatable 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 a single sentence of 14 words, front-loaded with the action verb and resource. It is efficient and contains no fluff. However, the extreme brevity sacrifices important context, preventing a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (4 required), no output schema, and no annotations, the description is too minimal. It does not explain return values, prerequisites, or the effect of optional parameters like 'subject' and 'key'. An agent would lack sufficient information to invoke the tool correctly without inspecting the schema.
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. The description does not add any meaning beyond the parameter names and schema descriptions. It does not explain 'profile' or 'subject' in the context of carving, nor does it clarify the relationship between 'in_ticks' and 'out_ticks'. No extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Cut') and identifies the resource ('master cut sheet', 'clip sheet', 'delivery shape'). It clearly distinguishes from siblings like 'splice' (joining) and 'draft' (creating) by describing a unique extraction operation. However, the term 'delivery shape' is domain-specific and not explained, slightly reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like 'splice' or 'draft'. It does not state prerequisites, when-not-to-use, or mention the idempotency key's role in avoiding duplicate clips. The usage context is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
colourB
Decide the colour treatment for a cut sheet, including whether a transfer stage is inserted.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| look | No | A look slot name declared in the party's kit. Null uses the settled finding. | |
| sheet | Yes | A cut sheet handle. | |
| target_range | No | sdr, hlg, or pq. | sdr |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects and safety profile, but it only states that it decides colour treatment without indicating whether it modifies the cut sheet, requires permissions, or what the output is. The phrase 'including whether a transfer stage is inserted' hints at a possible mutation but is ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the verb and object, with no wasted words. However, it is under-specified, which is a completeness issue rather than a conciseness issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters with an enum and no output schema, requiring the description to explain return values and effects. The description does not cover what happens after the decision, what a 'transfer stage' is, or what the caller should expect, making the tool under-explained.
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?
All four parameters have schema descriptions (100% coverage), so the description itself adds no additional meaning to the parameters. The term 'cut sheet' aligns with the `sheet` parameter, but no deeper semantics are provided beyond the schema.
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 uses the specific verb 'Decide' with the resource 'cut sheet' and mentions a key aspect (transfer stage insertion), making its function clear and distinct from sibling tools like apply or preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided; the description does not mention when to use this tool over alternatives or any prerequisites/exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deliverB
Encode and mux the finished deliverable for a cut sheet.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| sheet | Yes | A cut sheet handle. | |
| motion | No | Which overlay renderer to use. null adopts whatever the sheet's caption job was built with, and 'still' otherwise. An explicit value that disagrees with the caption job refuses. |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the core operation, omitting key traits such as whether the tool is asynchronous, idempotent (beyond the key parameter), destructive, or requires specific sheet states. The one-word 'finished' implies a prerequisite but does not elaborate on failure modes or side effects.
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 a single, well-constructed sentence that front-loads the main action without filler. It earns a 4 for efficiency, though a second sentence elaborating on usage or behavior would have made it a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (one required), no output schema, and no annotations, the description is insufficiently complete. It fails to explain what the tool returns, whether it is synchronous, or what state the sheet must be in before calling. For a tool performing encoding and muxing—operations that could be slow or error-prone—this information is critical for correct invocation.
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%—all three parameters (key, sheet, motion) already have clear descriptions in the schema. The tool description adds no additional meaning about parameter usage, constraints, or interactions. A baseline of 3 is appropriate since the description does not degrade understanding but also does not enhance it.
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 clearly states the tool's action with specific verbs ('encode and mux') and identifies the resource ('finished deliverable for a cut sheet'). This verb+resource combination is distinct from sibling tool names like 'inspect', 'draft', or 'preview', enabling an agent to differentiate it easily.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. Siblings like 'preview' or 'verify' might be used before or after delivery, but the description does not mention prerequisites, sequencing, or conditions that would help an agent decide between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
draftC
Start a new cut sheet for a party from a source, a bookmark and a delivery profile.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| party | Yes | A party identifier — a directory under casebook/parties/. | |
| source | Yes | A source handle. | |
| profile | Yes | A delivery profile name. | |
| bookmark | Yes | A bookmark name. | |
| situation | No | The name of a situation block declared in that party's party.toml. | default |
TDQS
C2.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral transparency. The description implies a state change ('start a new cut sheet'), but it doesn't disclose what this operation does beyond creation (e.g., does it write files? interact with an API? trigger a workflow?). It doesn't mention destructive potential or idempotency behavior (despite having a 'key' parameter). It is adequate but leaves many behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that names three key building blocks (source, bookmark, delivery profile). It is not verbose, but it is terse to the point of lacking important context. The sentence structure is straightforward but not front-loaded with enough clarifying detail. Some wasted opportunity exists because it could briefly explain the domain jargon without being much longer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description could compensate but does not explain what the tool returns or how to use the result. With six parameters (four required), the description only briefly references three of them and does not cover 'key' or 'situation'. The sibling tools suggest a workflow (inspect, splice, verify, deliver) but the description does not position draft within that pipeline. Overall, the description feels incomplete for a tool that probably initiates a multi-step process.
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%, so the baseline is 3. The description adds slight context by naming three parameters (source, bookmark, delivery profile) that are part of the tool's core inputs, but does not explain what these domain concepts mean or how they relate to each other. The 'party' parameter is mentioned in vague terms ('directory under casebook/parties/'), but the description adds no additional meaning beyond the schema. The 'key' parameter hint at idempotency but the description does not address it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description tells us the tool starts 'a new cut sheet for a party' given source, bookmark, and delivery profile, but it uses domain jargon ('cut sheet', 'bookmark', 'delivery profile') without explanation. Among sibling tools like inspect, splice, verify, deliver, it's not instantly clear what distinguishes 'draft' from other actions. The verb 'start' and noun 'cut sheet' provide a basic purpose, but the domain terms make it vague for a general AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings like splice, deliver, or verify. It doesn't mention prerequisites (e.g., must party exist? Must source be valid?), nor does it explain that the idempotency key is optional but recommended. The agent has no context for deciding to call draft over other tools in the set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hearA
Transcribe a source to words with timings, reading the result as text before anything encodes.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | draft, local, or cloud. | local |
| source | Yes | A source handle. | |
| consent | No | Consent token. Required only when tier is cloud. | |
| language | No | BCP-47 tag, or auto. | auto |
TDQS
A3.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions 'reading the result as text before anything encodes' but does not explain what 'encodes' means, whether the operation is read-only, requires permissions, or has rate limits. Important behaviors like output format or side effects are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and avoids redundancy. Every word serves a purpose with no wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains the core transcription function, it omits details about the return format (how timings are represented), the role of 'tier' and 'consent', and does not compensate for the lack of an output schema. Given four parameters and no output schema, the description is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with minimal per-parameter descriptions (e.g., 'A source handle', 'draft, local, or cloud.'). The tool description adds meaning by stating the tool transcribes to words with timings and reads as text, enriching the context beyond the schema alone.
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 clearly states the tool transcribes a source to words with timings, using a specific verb ('transcribe') and resource (source). It also adds nuance about reading the result as text before encoding, which distinguishes it from siblings like 'caption'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'caption', 'draft', or 'sound'. The description only states what it does without offering context on when it is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspectC
Read a media file's shape and mint a source handle for it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Workspace-relative path to a media file. | |
| include | No | Extra maps to compute: any of 'quiet', 'loudness'. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-like operation ('Read'), but also mentions 'mint a source handle', which suggests creating something (a handle) and may have side effects. The description does not disclose whether this operation is reversible, requires authentication, or has rate limits. The term 'mint' is ambiguous and could mislead an agent about the tool's side effects.
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 a single sentence of moderate length, conveying the core purpose concisely. It is front-loaded and contains minimal redundancy. However, it could be slightly more compact by removing 'a media file's shape and' since 'Read a file' might suffice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that no output schema is provided, the description should clarify what a 'source handle' is and whether the tool returns it or something else. It also doesn't mention that 'include' is optional or what defaults apply. The tool has 18 siblings with various media actions (draft, splice, verify, etc.), but the description provides no context for how 'inspect' fits with those. The description is incomplete for a tool that mints a handle.
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?
The input schema already has high coverage (100%) with descriptions for both 'path' (workspace-relative path) and 'include' (extra maps to compute). The description does not add any additional semantics beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reading a media file's shape and minting a source handle. The verb 'Read' and noun 'media file' are specific, though the term 'shape' is somewhat vague. It distinguishes from siblings like 'inspect' (which is the tool itself) and 'stock', 'sound', 'colour' that likely deal with different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'draft', 'verify', or 'preview'. It does not mention any prerequisites (e.g., file existence, permissions) or exclusions (e.g., unsupported media types). The agent is left to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
placeB
Place an element onto a cut sheet at a tick for a hold.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| sheet | Yes | A cut sheet handle. | |
| fields | No | Values for the element's declared text slots. | |
| element | Yes | An element name from elements/. | |
| at_ticks | Yes | When it appears. | |
| hold_ticks | Yes | How long it stays. At least one frame in the sheet's cadence. |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description implies a write/mutation operation ('Place an element') but does not state whether it is destructive, reversible, or requires specific permissions. It adds value by specifying placement constraints (at a tick, for a hold) but fails to disclose other essential behaviors like idempotency (though 'key' parameter hints at it) or effects on existing sheet elements.
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 a single, focused sentence that states the core action without unnecessary detail. It could be improved by placing domain-specific terminology in a more front-loaded manner, but overall it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex domain (cut sheets, elements, ticks, holds) and lack of output schema, the description is partially complete. It explains the what, where, and when but omits return values or side effects. With no annotations and no output schema, more detail is warranted for a tool with 6 parameters and nested objects, especially to clarify the 'fields' object and idempotency behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions (100% coverage), and the description complements this by explaining the domain-specific action for the main parameters ('at a tick' and 'for a hold'). However, the description does not clarify the 'fields' parameter syntax or the role of 'key', leaving some semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Place an element'), the target ('onto a cut sheet'), and the conditions ('at a tick for a hold'). It distinguishes from siblings like 'splice' or 'draft' which suggest different operations. However, it does not differentiate from potential similar tools like 'apply', and lacks a verb-resource structure that fully clarifies domain-specific terms like 'element', 'cut sheet', 'tick', and 'hold'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings. With 17 siblings including tools like 'inspect', 'draft', and 'preview', an agent has no context for choosing 'place' over alternatives. There is no mention of prerequisites (e.g., must a sheet be created first?), exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
previewC
Preview a bounded span of a cut sheet at a chosen rung.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rung | No | Preview ladder rung: 1 h264_qsv, 2 libx264, 3 mpeg4. | |
| sheet | Yes | A cut sheet handle. | |
| in_ticks | No | Start of the span to encode. | |
| out_ticks | No | End of the span. -1 means the whole sheet. |
TDQS
C2.7/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits like read-only vs. mutation, side effects, or permissions. The description only states the action without mentioning whether 'preview' is a read operation, what it produces, or any state changes. This is a serious gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the core action with zero wasted words. Every part is meaningful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema, yet the description does not explain what preview produces (e.g., a video clip, thumbnail, or report), whether it modifies state, or what the output format is. Critical operational context is missing.
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%, so the baseline is 3. The description echoes the parameter concepts (bounded span, rung) but does not add new semantic meaning beyond what the schema already provides. No additional context or constraints are introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Preview' and the resource 'bounded span of a cut sheet at a chosen rung', clearly indicating the action and target. However, given sibling tools like 'inspect', 'hear', and 'watch', it does not differentiate preview from those, so it misses the chance to clarify the unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'inspect' or 'hear'. There are no explicit use cases, prerequisites, or exclusion criteria, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quoteB
Locate where something was said in a source, and get the tick range it was said in.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Words to look for. Empty means everything in the range. | |
| limit | No | Maximum hits to return. | |
| source | Yes | A source handle. | |
| in_ticks | No | Start of the window to search. | |
| out_ticks | No | End of the window. -1 means end of source. |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should reveal behavior. It states what the tool does but does not disclose matching rules (case sensitivity, partial matches), error handling (e.g., text not found), or side effects. Returns tick range but format unspecified.
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 a single, clear sentence with no wasted words. However, it could be slightly more structured (e.g., listing output) without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description is too minimal. It fails to explain the return format, ordering of results, or behavior when no match is found – critical for correct agent invocation.
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%, so each parameter already has a clear description. The tool description adds no additional meaning beyond what the schema provides – baseline 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 description uses a specific verb ('Locate') and resource ('something said in a source') and clearly states the output ('get the tick range'). This distinguishes it from sibling tools like 'hear' (listen) or 'caption' (transcribe).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., 'hear' for listening, 'inspect' for metadata). No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
soundC
Resolve the sound plan for a cut sheet: the music lane, its level, and the loudness target.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| music | No | An asset handle to place on the sound lane. | |
| sheet | Yes | A cut sheet handle. | |
| target_loudness | No | A loudness target name from the delivery profile. | |
| music_level_millibel | No | Music level in millibel. Bounds are declared in code; an out-of-bounds value is refused, never clamped. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It only says 'resolve' without explaining what that entails (e.g., does it modify state? require authorization? revertible?). The presence of an idempotency key (key param) hints at safe retries, but this is neither stated nor elaborated. The description fails to clarify whether the tool is read-only or mutating, a critical gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence of 17 words. Every phrase ('resolve the sound plan', 'music lane', 'level', 'loudness target') directly contributes to understanding. No fluff or redundancy. Excellent conciseness for a tool with 5 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good parametric documentation in the schema, the description omits crucial details: what the tool returns (no output schema), the nature of 'resolve' (analysis vs. mutation), edge cases (e.g., out-of-bounds music level is refused, not clamped), and required permissions. For a tool with no annotations and moderate complexity, this brief description leaves an agent underinformed.
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 baseline is 3. The description adds 'the music lane, its level, and the loudness target', which maps to music, music_level_millibel, and target_loudness, reinforcing their roles. However, it does not explain parameters beyond what the schema already states (e.g., 'key' for idempotency, 'sheet' as the cut sheet handle). No new semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: resolving a sound plan for a cut sheet, specifying the music lane, its level, and loudness target. This distinguishes it from siblings like 'hear' or 'preview' which likely involve playback or review, not planning. However, the verb 'resolve' is somewhat vague—could mean compute, finalize, or apply—reducing precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'draft', 'apply', or 'hear'. The description implies use when setting up a sound plan, but does not state exclusions, prerequisites, or typical workflows. Without this, an agent may misuse the tool in contexts better served by a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
spliceC
Add a segment to the cut sheet, or amend an existing segment's edges.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| why | No | One line for the human reviewer. Never reaches pixels. | |
| cause | Yes | speech, manual, restored, or pad. | |
| sheet | Yes | A cut sheet handle. | |
| source | Yes | A source key from the sheet's sources[]. | |
| segment | No | When given, amend that segment instead of adding one. | |
| in_ticks | Yes | First deliverable tick kept (the body entry's in). | |
| out_ticks | Yes | First deliverable tick not kept (the body entry's out). | |
| source_in_ticks | Yes | Source tick where the kept range begins (pick.in); pick.out is derived. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only mentions adding or amending segments but omits critical behaviors such as idempotency (key parameter), error conditions (e.g., missing sheet or source), or the effect of the 'segment' parameter. The hint about 'why' never reaching pixels is a minor detail but insufficient overall.
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 a single sentence, front-loaded with the key actions. It is concise and avoids excess words, though it could be slightly more structured to separate the two modes (add vs. amend) for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, 6 required, no output schema, no annotations), the description is too brief. It does not explain what a 'cut sheet' is, what happens on success, error handling, or how the output is returned. The agent has insufficient context to use the tool correctly without additional knowledge.
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%, so the schema already documents each parameter. The description adds minimal semantic value beyond the schema—it loosely maps 'amend' to the 'segment' parameter but does not elaborate on tick semantics or the relationship between parameters. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a segment' or 'amend an existing segment's edges') and the resource ('cut sheet'). It is specific and distinguishes the tool's purpose from generic operations, though it could benefit from clarifying what a 'cut sheet' is in the context of the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use splice versus other tools like 'carve', 'stock', or 'sound'. There is no mention of prerequisites, alternatives, or contexts where this tool is appropriate or inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
stockC
Search licensed third-party music and hits, and record the rights for one that fits.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Idempotency key. | |
| kind | Yes | music, hit, footage, still or typeface. | |
| limit | No | Maximum candidates. | |
| terms | No | Search terms. | |
| acquire | No | A candidate id from a previous call. Downloads it and records its rights. | |
| refresh | No | Asset handles to re-capture terms for, or the single token '*'. | |
| seconds_min | No | Reject anything shorter, in whole seconds. |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It merely says 'search and record rights' without detailing side effects (e.g., that acquire downloads and creates a record, or that the tool is idempotent via the 'key' parameter). The schema descriptions fill some gaps, but the tool description itself lacks essential behavioral context.
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 a single, front-loaded sentence of 14 words. It is concise and efficient, but it sacrifices precision and completeness for brevity. It could be slightly improved without losing conciseness, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations), the description is too sparse. It fails to explain the search-then-acquire workflow, the role of the idempotency key, or the meaning of the 'refresh' and 'seconds_min' parameters. The description is inadequate for correctly invoking the tool in all scenarios.
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% (all 7 parameters have descriptions). The tool description adds minimal additional meaning beyond the schema – it maps 'search' to 'terms' and 'record rights' to 'acquire', but does not clarify other parameters like 'refresh', 'seconds_min', or 'kind'. Baseline 3 is appropriate given high schema coverage and limited added value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search licensed third-party music and hits, and record the rights for one that fits.' It identifies a verb+resource but is partially inaccurate: the schema allows searching footage, stills, and typefaces in addition to music and hits. The purpose is vaguely clear but not fully aligned with the tool's capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its many siblings (e.g., inspect, hear, preview). There is no mention of prerequisites, alternatives, or when not to use it. The description implies a search-and-acquire workflow but offers no explicit selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
trialC
Find out what this machine can actually do, by test-encoding rather than by reading a feature list.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| what | No | Which surveys to run. | |
| force | No | Ignore the cached result and re-run the test encodes. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'test-encoding' and cached results (via force param), but does not disclose side effects, performance characteristics, or what the tool actually runs internally. Minimal behavioral insight.
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?
Single sentence, no fluff. Front-loaded with action verb. Could be slightly more structured, but efficiency is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and low parameter count (2, none required). Description does not explain return values or what 'surveys' are. For a discovery tool, it is moderately complete but leaves gaps for an AI agent to interpret 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% (both parameters have descriptions in the input schema). The description adds the context of 'test-encoding' but does not provide additional semantics beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose is to discover machine capabilities via test-encoding rather than feature lists. It uses a specific verb ('find out') and resource ('capabilities'), but does not differentiate from sibling tools like 'inspect' or 'hear'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description implies it is for exploration, but does not specify when not to use it or provide alternative tool names for missing filtering functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verifyC
Run every gate against a cut sheet and report what passes and what blocks.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | Yes | A cut sheet handle. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It states the tool 'run[s] every gate' and reports pass/block status, but doesn't mention side effects (e.g., does it modify the sheet?), permissions needed, failure modes, or performance implications (e.g., is it expensive for many gates?).
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 a single, clear sentence that efficiently communicates core purpose. Could arguably be more specific (e.g., defining 'gate'), but is not verbose or wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 parameter with full schema coverage and no output schema, the description is adequate for basic use. However, given absence of annotations and output schema, the description could better explain what 'passes' vs 'blocks' means in the return format to compensate.
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?
The schema already has 100% description coverage defining 'sheet' as 'A cut sheet handle', so the baseline is 3. The description doesn't add further parameter semantics (e.g., what a valid handle looks like), but the schema is sufficient for this single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('run every gate') and identifies the domain ('cut sheet'), clearly differentiating it from sibling tools like 'inspect' or 'draft'. However, it doesn't explain what a 'gate' is, which slightly reduces clarity for agents unfamiliar with the domain jargon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus siblings like 'inspect' (which might also analyze a sheet) or 'draft'. It implies verification use via 'report what passes and what blocks' but lacks exclusions or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
watchB
Track shot changes and the subject through a source, producing a framing path.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | A source handle. | |
| subject | No | largest, centre, or none. | largest |
| out_shape | No | Target frame shape the path is planned for, as width:height. | 9:16 |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states the tool tracks shot changes and framing path, implying analysis rather than output creation. However, it does not mention whether this tool modifies state, requires specific permissions, or what system constraints apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, front-loading the core action and output. It is appropriately succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool deals with framing paths and output shape, the absence of an output schema is notable. The description does not explain what 'framing path' means or what the tool returns, and the sibling tools list is large with no differentiation hints. The description lacks sufficient context for effective tool selection.
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%, so the schema already documents all three parameters. The description mentions 'track shot changes and the subject' which implies the 'subject' and 'source' parameters but adds no extra detail beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('track shot changes and the subject') and a clear resource ('source'), producing a 'framing path'. While it distinguishes the tool's purpose, it could better differentiate from siblings like 'inspect' or 'hear' that might also analyze a source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'inspect', 'hear', or 'preview'. The description does not mention non-use cases, context, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
18 tool updates
v0.0.0- First observed
apply - First observed
cancel - First observed
caption - First observed
carve - First observed
colour - First observed
deliver - First observed
draft - First observed
hear - First observed
inspect - First observed
place - First observed
preview - First observed
quote - First observed
sound - First observed
splice - First observed
stock - First observed
trial - First observed
verify - First observed
watch
TDQS
B3.3/5.0
Scored across 18 tools
Disambiguation4/5
Most tools have clearly distinct purposes (e.g., inspect reads media, draft starts a cut sheet, splice adds segments, hear transcribes). A few pairs like 'splice' and 'place' could be confused in the abstract, but descriptions differentiate them. Overall, an agent can reliably distinguish tools.
Naming Consistency5/5
All tool names are single-word verbs in lowercase, following a highly consistent pattern. Names like 'splice', 'carve', and 'trial' are domain-appropriate and uniform, with no mixing of conventions.
Tool Count5/5
18 tools cover a comprehensive media editing workflow—ingest, editing, verification, delivery, and auxiliary operations. The count feels well-scoped for the domain, with each tool serving a necessary function and no redundancy.
Completeness4/5
The toolset covers the core editing lifecycle well (from source intake to final delivery). Minor gaps exist, such as a lack of tools for deleting segments, managing sources, or listing projects, but these are not critical to the main editing flow.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Make videos and docs with your AI agent — describe what you need, every output stays editable.
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Orccut: a real timeline video editor for AI agents - journaled edits, FFmpeg/MLT rendering
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to edit video assemblies from A-roll and B-roll, add captions, and publish to social media platforms.277 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to autonomously edit videos into publish-ready vertical short-form content, including silence removal, subtitle generation, voiceover synthesis, color grading, and composite pipeline creation.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to generate cinematic video and image assets and perform autonomous timeline assembly, multi-track audio editing, chroma-key compositing, and local draft manipulation from conversational prompts.2MIT