Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hyperframes-mcp Render the intro composition in project launch to mp4."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Self-hosted MCP server that exposes the HyperFrames
CLI as agent tools. Runs on our own infra — agents connect to our endpoint,
not HeyGen's hosted connector (mcp.heygen.com) nor the browser-only WebMCP
surface of the Studio.
Tool | What it does |
| Lists HyperFrames projects in the workspace |
| Lists a project's compositions (JSON) |
| Runs the HyperFrames linter (a11y/layout/motion) |
| Renders a project/composition → mp4/webm/mov/gif/png-sequence |
| Captures PNG frames for visual QA |
| Scaffolds a new project from an example |
| Status + log of a render/snapshot job |
| Recent jobs and queue state |
| Blocks until a job finishes (or times out) |
| Cancels a queued or running job |
Rendering runs inside the container (chrome-headless-shell + ffmpeg bundled), so no external accounts or credits are needed.
render_video and snapshot_frames enqueue the work and return a job_id
immediately — a render takes minutes and must not hold the HTTP request open.
Follow it with get_job / wait_job / list_jobs / cancel_job, or pass
wait: true for short clips. Jobs are persisted to disk (HF_JOBS_DIR) so their
status survives restarts; render concurrency is capped by HF_JOB_CONCURRENCY.
Related MCP server: video-agent-mcp
HTTP (hosted): MCP_TRANSPORT=http, served at POST /mcp
(Streamable HTTP, stateless). Rendered files are downloadable at
GET /files/<path-relative-to-workspace>.
stdio (local): MCP_TRANSPORT=stdio — for Claude Code / Cursor / Codex.
Live: https://hyperframes-mcp.lab.whitelabel.lat
{
"mcpServers": {
"hyperframes": {
"type": "http",
"url": "https://hyperframes-mcp.lab.whitelabel.lat/mcp"
}
}
}If MCP_AUTH_TOKEN is set, add "headers": { "Authorization": "Bearer <token>" }.
{
"mcpServers": {
"hyperframes": {
"command": "docker",
"args": ["run","-i","--rm","-e","MCP_TRANSPORT=stdio","hyperframes-mcp:latest"]
}
}
}POST /mcp — MCP (Streamable HTTP)
GET /health — liveness (public; includes queue state)
GET /jobs — list jobs (queue state + recent)
GET /jobs/<id> — single job status/log
POST /jobs/<id>/cancel — cancel a job
GET /files/<path> — download rendered artifacts
GET / — tool index
Var | Default | Meaning |
|
|
|
|
| HTTP port |
| (empty) | If set, require |
|
| Where projects live |
|
| Where job records are persisted |
|
| Max renders/snapshots running at once |
|
| Log lines kept per job |
|
| Cap for |
|
| Upstream checkout / CLI entry |
|
| Render timeout (30 min) |
Rendering is CPU/RAM heavy → it runs through a persistent job queue
(src/jobs.js) with capped concurrency, so the MCP request returns instantly.
The image is large (Chrome + ffmpeg + the full toolchain) and the build clones
upstream at a pinned commit (HF_REF) for reproducibility.
Not a fork of upstream — this repo carries only the server + deployment recipe.
Cancela un job en cola o en ejecución.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full burden of behavioral disclosure. It only states the cancellation action and the eligible job states; it does not mention whether cancellation is reversible, whether it has side effects on the job's output, or whether canceling an already-finished job is an error. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler or repetition. Every word adds useful meaning by specifying both the target ('job') and the eligible states ('en cola o en ejecución').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but with no annotations and no output schema, the description still leaves important gaps: it does not cover cancellation outcomes, edge cases, prerequisites, or behavior after the job is canceled. For a mutating tool, this is not complete enough for an agent to safely understand its effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter job_id is documented in the schema only as a string, and the description adds no extra meaning about how to obtain it or how it maps to the job being canceled. The parameter name is self-explanatory, but the description does not compensate for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Cancela') and resource ('job') and narrows the scope to jobs 'en cola o en ejecución'. It does not explicitly differentiate the tool from siblings like get_job or wait_job, but its purpose is still clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'en cola o en ejecución' gives some context about when cancel_job applies: queued or running jobs. However, it does not explicitly state when not to use it, nor does it name alternatives such as waiting with wait_job or inspecting status with get_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crea un proyecto HyperFrames nuevo a partir de un ejemplo. Devuelve el nombre del proyecto.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Nombre del proyecto nuevo | |
| example | No | Ejemplo base (blank, warm-grain, swiss-grid, kinetic-type, product-promo…) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It explicitly discloses the core mutation (creates a new project) and the return value (project name). However, it does not mention failure modes, overwrite behavior, prerequisites, or side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The primary behavior is front-loaded and the return value is explicitly stated. Every phrase contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter creation tool, the description is mostly complete: it explains the action, the example-based source, and the return value. The main gap is the lack of usage guidance relative to sibling tools, but the schema covers parameter semantics and no output schema is required given the return is explicitly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters 'name' and 'example' are already documented. The description adds minimal semantic value by linking the action to an example, but it does not explain optionality, default behavior, or example value formatting beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Crea un proyecto HyperFrames nuevo') and a distinguishing mode ('a partir de un ejemplo'), while also specifying the return value. This clearly differentiates create_project from sibling tools like list_projects, render_video, and write_project_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives, such as write_project_file for modifying existing projects or list_projects for reading. The word 'nuevo' implies creation, but there are no when-to-use or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estado y log de un job (render o snapshot) por su job_id.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ID devuelto por render_video / snapshot_frames |
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. It only states what the tool returns (status and log) but does not mention side effects (e.g., read-only), error handling, or what happens if the job ID is invalid. The description adds minimal behavioral context beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core function and scope. There is no wasted wording, and all essential information (status, log, job type, identifier) is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one well-documented parameter, the description is adequate. However, it does not address when to use this over wait_job or list_jobs, and it lacks any note about return format or error cases. Given the sibling context, the description is minimally sufficient but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for job_id, including its provenance (returned by render_video / snapshot_frames). The description merely repeats 'by its job_id' without adding new meaning. Since schema coverage is high, the baseline is 3, and the description does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the status and log of a specific job (render or snapshot) identified by job_id. This is a precise verb-resource combination that distinguishes it from sibling tools like list_jobs (which lists all jobs) or wait_job (which waits for completion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly say when to use this tool versus alternatives such as wait_job or list_jobs. The use case is implied (checking a specific job's status/log), but no explicit context, exclusions, or alternative selection guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corre el linter de HyperFrames sobre un proyecto (accesibilidad, layout, motion). Salida JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Nombre del proyecto | |
| verbose | No | Incluir hallazgos de nivel info |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Al no haber anotaciones, la descripción asume toda la carga de informar el comportamiento. Añade que el linter cubre tres categorías y que la salida es JSON, pero no detalla la estructura de resultados, si es síncrono, si modifica el proyecto o qué ocurre ante un proyecto inexistente.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Una oración compacta y con alta densidad informativa: verbo, recurso, alcance y salida. No hay redundancias y la información clave aparece al principio.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Para un tool simple de 2 parámetros y sin objetos anidados, la descripción es casi suficiente: el agente sabe qué parámetros pasar y que recibirá JSON. No obstante, la ausencia de esquema de salida y de detalles sobre los hallazgos devueltos genera un vacío para interpretar el resultado.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
El esquema ya documenta ambos parámetros con cobertura del 100%, así que la descripción no necesita aportar más semántica paramétrica. La mención a JSON no complementa los parámetros, por lo que se mantiene la línea base de 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
La descripción abre con el verbo específico 'Corre el linter' y el recurso 'proyecto', delimita el alcance (accesibilidad, layout, motion) y anuncia el formato de salida. Esto la distingue claramente de las herramientas hermanas de gestión de proyectos, vídeo y jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
El uso queda implícito: se ejecuta sobre un proyecto para obtener hallazgos de linting, y el alcance citado sugiere cuándo aplica. Sin embargo, no menciona excepciones, condiciones previas ni alternativas, aunque no hay un hermano que sea sustituto natural.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista las composiciones de un proyecto (archivos .html). Salida JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Nombre del proyecto dentro del workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It does disclose the output format ('Salida JSON') and implicitly signals a read-only listing operation via 'Lista.' It does not mention error behavior, authorization needs, or whether the project must exist, but for a simple list operation these are relatively minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single economical sentence that front-loads the action and object, specifies the file type, and states the output format. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one required parameter and no output schema, the description provides sufficient context: what is listed, for which project, file type, and JSON output. It does not enumerate the JSON fields or pagination behavior, but those are not strictly necessary for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the only parameter, 'project,' and the schema description coverage is 100%. The tool description adds context that compositions are .html files, but it does not materially enhance the parameter meaning beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Lista'), a clear resource ('las composiciones de un proyecto'), and adds a clarifying detail that these compositions are .html files. This clearly distinguishes it from sibling tool list_projects, which lists projects themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to list the compositions belonging to a project. However, it does not explicitly mention alternatives or conditions such as 'use list_projects to discover available projects' or 'use lint_project for validation.' The usage context is acceptable but not richly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista los jobs recientes (más nuevos primero) y el estado de la cola.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Máximo de jobs (def 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the sorting order (newest first) and that queue status is included, but it does not describe the return shape, pagination behavior, or whether the result is limited to the current user/workspace.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the resource, the ordering, and the extra queue-status output in just a few words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description provides the essential return information: recent jobs and queue status. It is complete enough for an agent to call it correctly, though it could optionally clarify the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the limit parameter is already documented with its default value ('Máximo de jobs (def 20)'). The description adds no extra semantics beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Lista'), resource ('jobs recientes'), and defines ordering ('más nuevos primero') plus the additional queue status output. This clearly distinguishes it from sibling tools like get_job (single job) and list_projects/list_compositions (different resources).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to see recent jobs and queue status. However, it does not explicitly state when not to use it, such as when needing a specific job's full details (use get_job) or when checking whether a job completed synchronously (use wait_job).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista los proyectos HyperFrames del workspace (cada uno con su index.html).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits such as read-only nature or side effects. The description only says 'Lista' (lists), which implies a read operation, but does not explicitly state that it is non-destructive or requires any permissions. No additional context about behavior is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the verb and resource immediately, followed by a clarifying detail about index.html. There is no wasted text, making it appropriately concise for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with no output schema, the description is nearly complete. It identifies the resource and includes a detail about the expected contents (index.html). It does not describe the return format or pagination, but for a simple list operation this may be sufficient. The omission of response structure prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is complete with 100% coverage. Per the rubric, a tool with 0 parameters receives a baseline of 4. The description adds no parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists HyperFrames projects in the workspace, using the specific verb 'Lista' and the resource 'proyectos HyperFrames del workspace'. It also adds detail about each project having an index.html. However, it does not explicitly differentiate from the sibling tool list_compositions, relying on the resource type alone to imply distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 list_compositions. It only states what it does, leaving the agent to infer usage from the resource name. There is no mention of when not to use it or any preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renderiza un proyecto/composición a MP4 (u otro formato: webm, mov, gif, png-sequence). Por defecto ENCOLA el trabajo y devuelve un job_id — el render es pesado y no debe bloquear la request; sigue el avance con get_job / wait_job. Usa wait=true para clips cortos.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | FPS (24,30,60… o racional 30000/1001) | |
| wait | No | true = bloquear hasta terminar (máx HF_WAIT_MAX_MS). Def false = encolar. | |
| format | No | mp4 (def) | webm | mov | gif | png-sequence | |
| output | No | Ruta de salida (relativa al proyecto) | |
| project | Yes | Nombre del proyecto | |
| quality | No | draft | looks (def) | delivery | standard | high | |
| timeout_ms | No | Timeout del render en ms (def 1800000) | |
| composition | No | Archivo de composición (ej. compositions/intro.html). Omitir = index.html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals the async queueing behavior, job_id return, the heavy non-blocking nature of renders, and the wait=true blocking option. It could additionally mention side effects on output paths or failure behavior, but the core operational behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. The main action is front-loaded, the default queueing behavior comes immediately after, and the wait guidance closes with a practical tip. No filler or redundant verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description gives enough operational context: formats, default async behavior, job_id return, progress tracking, and when wait=true is appropriate. It doesn't describe error conditions or exact wait=true return shape, but the workflow an agent needs to call this tool successfully is clearly explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains every parameter. The description adds a useful heuristic for wait (short clips) and clarifies the default queueing workflow, but it does not need to document each parameter. Baseline 3 is appropriate because the description adds marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Renderiza un proyecto/composición a MP4" and enumerates alternative formats. This clearly identifies the tool's function and differentiates it from sibling tools like snapshot_frames and list_jobs without requiring the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the default behavior (enqueues and returns a job_id), warns that rendering is heavy and should not block the request, and tells the agent to follow progress with get_job / wait_job. It also gives a concrete usage condition: "Usa wait=true para clips cortos." This is strong when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Captura frames PNG de una composición para control visual de calidad. Por defecto ENCOLA y devuelve un job_id (get_job / wait_job).
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Timestamps en segundos, ej '3.0,10.5,18.0' | |
| wait | No | true = bloquear hasta terminar. Def false = encolar. | |
| frames | No | Nº de frames equiespaciados (def 5) | |
| project | Yes | Nombre del proyecto | |
| timeout_ms | No | Timeout en ms (def 900000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool enqueues by default and returns a job_id, and that the wait parameter can block until completion. However, it does not disclose side effects like where frames are stored, permissions needed, or whether it modifies the project. This is partial transparency but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the core action. It efficiently conveys the primary function and the default async behavior without fluff. It could be slightly more structured (e.g., bullet points) but remains clear and compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is incomplete. It explains the enqueue behavior and job_id but does not clarify what happens to the captured frames, how to retrieve them after completion, or whether any prerequisite steps (like project creation) are needed. The mismatch between 'composition' in the description and the 'project' parameter adds confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description does not add new parameter semantics beyond the schema—it mentions the default enqueue behavior which is already in the 'wait' parameter description. Since the schema already explains the parameters, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (capture PNG frames), the target (de una composición), and the purpose (control visual de calidad). It distinguishes itself from siblings like render_video by specifying still frames for QC rather than a video render. The default enqueue behavior is also mentioned, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests usage for visual quality control and references get_job/wait_job for handling the asynchronous job, but it does not explicitly contrast with alternatives like render_video or state when not to use this tool. The default enqueue behavior is mentioned, but no exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bloquea hasta que el job termine (o se agote el timeout). Útil para agentes sin polling.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| timeout_ms | No | Máxima espera en ms (def 600000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral details, but it only states the blocking behavior and timeout. It does not explain what happens on timeout (error vs. return), whether the call is synchronous, side effects, or any required permissions. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action and includes a practical usage note. Every word earns its place, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, no output schema, and no annotations, the description is incomplete. It does not cover timeout behavior details, return values, error handling, or prerequisites (e.g., job must exist). An agent would need additional context to use it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (timeout_ms has a description, job_id does not). The tool description adds no parameter-specific information beyond the schema, and job_id remains undocumented in both places. The description does not compensate for the missing schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('blocks') and resource ('job'), and adds a usage hint about being for agents without polling, which hints at differentiation from sibling polling tools. It does not explicitly name an alternative, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context ('useful for agents without polling'), which implies when to use it instead of polling-based tools like get_job or list_jobs. It does not explicitly mention alternatives or exclusions, but the guidance is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escribe (o crea) un archivo dentro de un proyecto del workspace: HTML, CSS, SVG, JSON… Crea los directorios necesarios. Para binarios (PNG/JPG/MP4) usa encoding=base64. Permite crear un proyecto nuevo desde cero escribiendo su index.html.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Ruta relativa dentro del proyecto, ej 'index.html' o 'assets/z.png' | |
| content | Yes | Contenido (texto UTF-8, o base64 si encoding=base64) | |
| project | Yes | Nombre del proyecto (se crea si no existe) | |
| encoding | No | Def utf8 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It mentions creating directories and supporting base64, but does not state whether it overwrites existing files, what happens if a file exists, or any error conditions. This is a significant gap for a file-writing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the primary action first, then lists specifics. Every sentence adds value, and there is no fluff. It's well-organized for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behaviors needed to invoke the tool: file writing, directory creation, base64 encoding, and project creation. However, it omits details like return value, error handling, and overwrite semantics, which are relevant for an agent to interpret the outcome. Given no output schema, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters with 100% coverage. The description adds the note about using base64 for binaries and that directories are created as needed, providing slight extra context. However, it doesn't go beyond what the schema already conveys for path and content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes (or creates) a file within a project, lists supported file types, and mentions directory creation and base64 support. It also notes it can create a new project by writing index.html, which adds context. However, it does not explicitly contrast with the sibling create_project, so differentiation is incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage guidance for the encoding parameter (use base64 for binaries) but does not explain when to use this tool versus the sibling create_project or other file operations. There is no mention of when not to use this tool or any alternatives, leaving the agent to infer selection from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0cancel_jobcreate_projectget_joblint_projectlist_compositionslist_jobslist_projectsrender_videosnapshot_frameswait_jobwrite_project_fileScored across 11 tools
Each tool targets a distinct resource and action: projects, compositions, linting, rendering, snapshots, and job management (get, list, wait, cancel). No two tools overlap in purpose; even the job-related tools have clearly separated responsibilities.
All tool names follow the verb_noun snake_case pattern (e.g., list_projects, render_video, cancel_job). The convention is uniform with no stylistic mixing, making the API predictable and easy to navigate.
With 11 tools, the server is well-scoped for managing HyperFrames projects, covering creation, editing, linting, rendering, snapshots, and asynchronous job lifecycle. Each tool earns its place in the workflow without bloat.
The tool surface covers the core lifecycle: create/list projects, write files, lint, render, snapshot, and manage jobs. Minor gaps like delete_project or read_file exist, but agents can accomplish primary tasks without dead ends.
Plan, compare, price, generate, and recover AI video from compatible MCP clients.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
Inspect and edit media canvases, run existing Flows, and retrieve results. Vyrl MCP token required.
