Skip to main content
Glama

Wait for Video Project

wait_for_video_project
Read-onlyIdempotent

Polls an existing video project until it completes, fails, is canceled, or times out. Read-only. After a timeout, use the same project ID to resume checking. Use signed download URLs unchanged. In ChatGPT, show Magic Hour's result card for playback and download when the video completes.

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": {
      "id": "<id>"
    },
    "name": "wait_for_video_project"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesExisting project ID returned by the matching creation tool. Reuse this ID after a wait timeout.
timeout_secondsNoMaximum seconds for this wait call, finite and greater than zero. Timeout does not cancel the project or start another generation.
max_inline_downloadsNoReserved for compatibility. Video waits do not inline downloads; leave at zero.
poll_interval_secondsNoSeconds between status checks. Must be finite and nonnegative; values below 0.5 use 0.5 seconds.
include_inline_downloadsNoReserved for compatibility. Video waits return download links, never inline video, regardless of this value.

Output Schema

NameRequiredDescriptionDefault
idNoExisting project identifier, retained for subsequent status checks.
statusNoProject status such as complete, error or canceled; timeout means only this wait call ended.
messageNoWait timeout or recovery guidance, when present.
downloadsNoAvailable output files with exact signed URLs. May be absent until completion.
last_projectNoLast observed API project snapshot if the wait timed out after a successful status check.
project_typeYesKind of project being retrieved.
exact_download_urlsNoConvenience list of the same unmodified signed output URLs.
download_expiration_metadataNoExpiration metadata only. Never append it to a download URL.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / id / description
      Added value: +"Existing project ID returned by the matching creation tool. Reuse this ID after a wait timeout."
    • addedInput schema / properties / include_inline_downloads / description
      Added value: +"Reserved for compatibility. Video waits return download links, never inline video, regardless of this value."
    • addedInput schema / properties / max_inline_downloads / description
      Added value: +"Reserved for compatibility. Video waits do not inline downloads; leave at zero."
    • addedInput schema / properties / poll_interval_seconds / description
      Added value: +"Seconds between status checks. Must be finite and nonnegative; values below 0.5 use 0.5 seconds."
    • addedInput schema / properties / timeout_seconds / description
      Added value: +"Maximum seconds for this wait call, finite and greater than zero. Timeout does not cancel the project or start another generation."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "Existing project status and exact output links. A wait timeout is not a generation failure; resume with the same ID.",
      +  "properties": {
      +    "download_expiration_metadata": {
      +      "description": "Expiration metadata only. Never append it to a download URL.",
      +      "items": {
      +        "properties": {
      +          "download_index": {
      +            "description": "Zero-based index in the upstream download list, encoded as text.",
      +            "type": "string"
      +          },
      +          "expires_at": {
      +            "description": "Expiration timestamp provided by the API.",
      +            "type": "string"
      +          },
      +          "note": {
      +            "description": "Guidance for preserving the signed URL.",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "downloads": {
      +      "description": "Available output files with exact signed URLs. May be absent until completion.",
      +      "items": {
      +        "properties": {
      +          "url": {
      +            "description": "Use this signed download URL unchanged, including all query parameters.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "url"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "exact_download_urls": {
      +      "description": "Convenience list of the same unmodified signed output URLs.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "id": {
      +      "description": "Existing project identifier, retained for subsequent status checks.",
      +      "type": "string"
      +    },
      +    "last_project": {
      +      "description": "Last observed API project snapshot if the wait timed out after a successful status check.",
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Wait timeout or recovery guidance, when present.",
      +      "type": "string"
      +    },
      +    "project_type": {
      +      "description": "Kind of project being retrieved.",
      +      "enum": [
      +        "image",
      +        "video",
      +        "audio"
      +      ],
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "Project status such as complete, error or canceled; timeout means only this wait call ended.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "project_type"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changed
    • removedInput schema / properties / context
      Removed value: -{
      -  "description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"",
      -  "type": "string"
      -}
  3. Changed1 schema field changed
    • addedInput schema / properties / context
      Added value: +{
      +  "description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"",
      +  "type": "string"
      +}
  4. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only' line is largely redundant. It earns credit for behavior beyond the annotations: that a timeout leaves the project running and resumable, and that signed download URLs must be passed through unchanged. Those are exactly the non-obvious traits an agent needs when a wait returns without a finished video.

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?

Four short sentences, front-loaded with the core purpose and the terminal conditions. The 'Read-only' sentence duplicates an annotation and could be dropped, but the remaining sentences about timeout resumption, URL handling, and the ChatGPT result card each carry distinct information.

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?

With five parameters at full schema coverage, an output schema, and read-only/idempotent annotations, the remaining burden is behavioral: what happens on timeout and how to resume, and how to handle returned links. Both are addressed. The ChatGPT result-card instruction covers the one client-specific action an agent might otherwise miss.

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

Parameters3/5

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

Schema description coverage is 100%, and every parameter already documents its own default, bounds, and edge cases (e.g., poll intervals below 0.5 clamping to 0.5, timeouts not cancelling the project, download parameters being reserved no-ops). The description adds only the ID-reuse hint, which the schema's own id field also covers. Baseline 3 is correct.

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 opens with a specific verb and resource: 'Polls an existing video project until it completes, fails, is canceled, or times out.' That distinguishes a blocking wait from a one-shot status read, and the 'video' qualifier separates it from the audio/image wait siblings. It stops short of naming get_video_project as the non-waiting alternative, so differentiation is implied rather than explicit.

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

Usage Guidelines3/5

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

The description gives useful operational guidance for the retry path ('After a timeout, use the same project ID to resume checking') and a client-specific presentation rule for ChatGPT. However, it never states when an agent should choose this tool over get_video_project, or when a one-shot check would be preferable to polling. Usage is inferable from the polling semantics but not spelled out.

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.