Skip to main content
Glama

start_encode2_raw

Destructive

Submit a job with the raw query JSON.

The `query` dict can be either the wrapped form `{"query": {...inner...}}`
or the inner object directly — the underlying client auto-wraps if needed.

The inner query MUST have shape:
    {
        "source": "<url>",
        "encoder_version": 2,
        "format": [                 # ARRAY of output specs
            {
                "output": "mp4",    # STRING type field. NOT "format".
                ...                 # encoding params per the recipe
            }
        ]
    }

Common composition mistakes this tool catches up front:
- `"format": "mp4"` inside an entry instead of `"output": "mp4"`.
- Missing `output` field.
- Unknown `output` value.
- `format` as a string at the top level (must be an array).
- `advanced_hls` / `advanced_dash` / `webm_dash` / `hls_audio` without a
  non-empty `stream[]` array (not a drop-in `output` swap on the MP4
  shape — see `qencode://recipe/hls_abr`).
- `vmaf` without `distorted` (`source` = reference, `distorted` = encoded).
- `video_intelligence` without `mode` (use `mode: "description"`, not
  `features`). Source must be https://; `description` modes need ≥10s
  clip, `search` ≥4s — check duration before submit (metadata job).
- A `destination` that is not Qencode Media Storage (`s3://<bucket>/…`,
  AWS / R2 / Azure / FTP / presigned URLs) or carries `key`/`secret`. Copy
  `{destination_prefix}/{new filename or folder}`. Do not copy a listed
  object's `destination_url` as dest. `stitch[].url`, `distorted`, subtitle
  files, and `logo.source` follow the same public/`cdn_url` vs
  private/`destination_url` rule as `source`. Video Intelligence needs
  `cdn_url` (https only).
- Credentials inside any input URL (`s3://KEY:SECRET@…`), or an input
  pointing at a loopback / private / cloud-metadata host.
- `callback_url` that is not a public `https://` URL. Set it only to a
  webhook the user gave you.
These come back as `{"error": "..."}` without submitting. Fix the request
or tell the user; never ask the user for storage keys or passwords.

Example vmaf query (encoder v1 — set explicitly here):
    {
        "source": "https://example.com/original.mp4",
        "encoder_version": 1,
        "format": [{
            "output": "vmaf",
            "distorted": "https://example.com/encoded.mp4",
            "destination": {"url": "<destination_prefix>/vmaf.json"}
        }]
    }

Example video_intelligence query (encoder v2):
    {
        "source": "https://example.com/input.mp4",
        "encoder_version": 2,
        "format": [{
            "output": "video_intelligence",
            "mode": "description",
            "destination": {"url": "<destination_prefix>/vi"}
        }]
    }

Unlike `transcode_video`, this tool does **not** auto-inject
`encoder_version`. Set `"encoder_version": 2` at the top of the inner
query for all v2 outputs (`smart_thumbnail`, `ai_detection`,
`video_intelligence`, `m4a`, stitch jobs, …). Use `1` only for VMAF per
`qencode://recipe/vmaf_quality`.

Stitching: a stitch job uses a top-level `stitch` array *instead of*
`source` — the two are mutually exclusive, so do NOT also set `source`
(setting both makes the API reject the job). Each `stitch[]` entry is a
URL string or a `{"url": ..., "start_time": ..., "duration": ...}`
object. Media Storage clips: `cdn_url` if public, `destination_url` if
private — same rule as `source`. Example:
    {
        "encoder_version": 2,
        "stitch": [
            {"url": "https://example.com/in.mp4", "start_time": 0, "duration": 5},
            {"url": "https://example.com/in.mp4", "start_time": 148, "duration": 5}
        ],
        "format": [{
            "output": "mp4", "video_codec": "libx264",
            "audio_codec": "libfdk_aac", "bitrate": 2800,
            "framerate": "30", "keyframe": "60", "audio_bitrate": 128
        }]
    }

For complex queries — ABR ladders, DRM, stitching, callbacks — call
`search_qencode_docs(...)` then `fetch_qencode_doc(...)` to read the
matching recipe before composing.

After this returns a `task_token`, in the SAME reply call `list_jobs`
with that token. If the job is already Done with a playable video URL,
also `open_player`. If the deliverable is a json/txt/srt/vtt file, call
`fetch_job_result` and give the user both the URL and the extracted
content.

`payload` is an optional opaque callback tag echoed by Qencode, not the
job body (`query` is). It must be a string or omitted. If a JSON object
is passed, this tool returns `{"error": "..."}` asking you to retry
with a string — it does not stringify the object and does not submit.
Do not put `source` / `format` in `payload`.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "start_encode2_raw"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes
payloadNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / payload / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "additionalProperties": true,
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  2. Changed4 schema fields changed
    • removedOutput schema / additionalProperties
      Removed value: -false
    • addedOutput schema / oneOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "status_url": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "task_token": {
      +        "type": "string"
      +      },
      +      "upload_url": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "task_token"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "error": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "error"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties
      Removed value: -{
      -  "status_url": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  },
      -  "task_token": {
      -    "type": "string"
      -  },
      -  "upload_url": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  }
      -}
    • removedOutput schema / required
      Removed value: -[
      -  "task_token"
      -]
  3. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already flag the write/destructive/open-world profile, and the description adds real context: validation failures return `{"error": "..."}` without submitting, credentials/private hosts are rejected, and the agent must never ask users for storage keys. It stops short of describing return format beyond `task_token` and error behavior, but the output schema covers returns.

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?

Very long, but front-loaded with the core shape, then a bulleted list of common mistakes, then examples and workflow. The composition-error list is slightly repetitive (e.g. the output-vs-format point appears three ways), which keeps it below a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, raw-JSON submission tool with a free-form object parameter, the description covers schema shape, encoder_version rules, stitching, destinations, credentials, callbacks, and the follow-up job workflow. Output schema covers the return, so nothing critical is missing.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden and does: it specifies the wrapped vs inner `query` auto-wrap, the required inner shape with `format` as an array of `output` specs, and that `payload` must be a string (a JSON object triggers an error rather than being stringified). That is meaning well beyond the bare object 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?

States a specific verb+resource ('Submit a job with the raw `query` JSON') and immediately distinguishes itself from `transcode_video` by noting it does not auto-inject `encoder_version`. An agent can tell exactly what this tool does versus its main sibling.

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

Usage Guidelines5/5

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

Explicit routing: use `transcode_video` for auto-injection, call `search_qencode_docs` then `fetch_qencode_doc` for ABR/DRM/stitch/callback recipes, and after a `task_token` call `list_jobs` in the same reply (plus `open_player`/`fetch_job_result` for specific deliverables). It also names when-not cases such as stitch vs source mutual exclusivity.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.