Skip to main content
Glama

Detect faces

detect_faces

Starts an asynchronous face-detection task for a supplied image or video and returns its id and charge information. Use before a selected-face swap, then retrieve its status and detected faces with get_face_detection_results. Current API documentation describes detection as free; pricing may change. Use the named attachment fields first for ChatGPT files. Ask which file goes where if their roles are unclear. If a file fails, ask the user to attach it again and keep the requested settings.

Input Schema

NameRequiredDescriptionDefault
imageNoAttach the image from ChatGPT for this input.
videoNoAttach the video from ChatGPT for this input.
assetsNoProvide the assets for face detection
confidence_scoreNoConfidence threshold for filtering detected faces. * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.

Output Schema

NameRequiredDescriptionDefault
idYesThe id of the task. Use this value in the [get face detection details API](https://docs.magichour.ai/api-reference/files/get-face-detection-details) to get the details of the face detection task.
credits_chargedYesThe credits charged for the task.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / anyOf
      Added value: +[
      +  {
      +    "required": [
      +      "image"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "video"
      +    ]
      +  },
      +  {
      +    "properties": {
      +      "assets": {
      +        "required": [
      +          "target_file_path"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "assets"
      +    ]
      +  }
      +]
    • removedInput schema / properties / assets / required
      Removed value: -[
      -  "target_file_path"
      -]
    • addedInput schema / properties / image
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Attach the image from ChatGPT for this input.",
      +  "properties": {
      +    "download_url": {
      +      "description": "Exact HTTPS download URL supplied for the native ChatGPT attachment, including its signed query.",
      +      "title": "Download Url",
      +      "type": "string"
      +    },
      +    "file_id": {
      +      "description": "Native ChatGPT file identifier paired with download_url; not a local filesystem path.",
      +      "title": "File Id",
      +      "type": "string"
      +    },
      +    "file_name": {
      +      "default": "",
      +      "description": "Original attachment filename, when supplied by ChatGPT.",
      +      "title": "File Name",
      +      "type": "string"
      +    },
      +    "mime_type": {
      +      "default": "",
      +      "description": "Attachment MIME type, when supplied by ChatGPT.",
      +      "title": "Mime Type",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "download_url",
      +    "file_id"
      +  ],
      +  "title": "ChatGPTFile",
      +  "type": "object"
      +}
    • addedInput schema / properties / video
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Attach the video from ChatGPT for this input.",
      +  "properties": {
      +    "download_url": {
      +      "description": "Exact HTTPS download URL supplied for the native ChatGPT attachment, including its signed query.",
      +      "title": "Download Url",
      +      "type": "string"
      +    },
      +    "file_id": {
      +      "description": "Native ChatGPT file identifier paired with download_url; not a local filesystem path.",
      +      "title": "File Id",
      +      "type": "string"
      +    },
      +    "file_name": {
      +      "default": "",
      +      "description": "Original attachment filename, when supplied by ChatGPT.",
      +      "title": "File Name",
      +      "type": "string"
      +    },
      +    "mime_type": {
      +      "default": "",
      +      "description": "Attachment MIME type, when supplied by ChatGPT.",
      +      "title": "Mime Type",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "download_url",
      +    "file_id"
      +  ],
      +  "title": "ChatGPTFile",
      +  "type": "object"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "assets"
      -]
  2. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the asynchronous task model, that a task id and charge information are returned, and the pricing caveat ("Current API documentation describes detection as free; pricing may change"), which is not derivable from structured fields. It stops short of describing polling/expiry behavior for the returned task id, keeping it below a 5.

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?

It is front-loaded with the action and the ordering guidance, and every sentence has a job. The pricing sentence is the weakest link and the trailing "keep the requested settings" is slightly vague, but nothing is redundant with the name or annotations.

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

Completeness4/5

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

With an output schema present, return values need not be re-explained, and the description appropriately summarizes only that an id and charge info come back. It covers the async flow, the successor tool, file-attachment handling and failure recovery, which is adequate for a task-initiating tool with mutually exclusive input branches. Minor gaps: it does not state how the task id should be polled or whether one invocation may accept multiple inputs.

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 coverage is 100%, so the baseline is 3. The description still adds meaning the schema cannot: it tells the agent to prefer the named attachment fields (image/video) over the assets path for ChatGPT files and to clarify roles with the user when ambiguous, which is a selection rule across the anyOf branches. The confidence_score parameter is left entirely to the schema, which is acceptable given full coverage.

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 first sentence states a specific verb and resource ("Starts an asynchronous face-detection task") plus the input domain (image or video) and what comes back (id and charge information). It explicitly distinguishes itself from get_face_detection_results by framing this tool as the initiator versus the retriever, so an agent can pick correctly without opening either schema.

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?

It names the ordering constraint ("Use before a selected-face swap") and routes to the explicit sibling for follow-up ("then retrieve its status and detected faces with get_face_detection_results"). It also gives input-selection guidance ("Use the named attachment fields first for ChatGPT files") and a disambiguation rule ("Ask which file goes where if their roles are unclear"), which is genuinely actionable when the agent cannot infer roles.

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.