Clueso

Add article media (image or GIF)

add_article_media

Add a screenshot or GIF to the article. It goes right after the block holding the screenshot named in after ("start" for the top), in place of the screenshot named in replace, or else at the end of the article. Returns its screenshot_id (it appears in the article as <SCREENSHOT screenshot_id>) and the new article_version.

kind="image": one of timestamp (capture a frame from the project's base video), mcp_upload_id (an uploaded image: mup_… from upload_file, or a Clueso upload_id), source_url (an image URL, e.g. one generate_media returned) or prompt (generate an AI illustration for the article; optional style_id and aspect_ratio, default 16:9). A generated image costs AI credits like generate_media's and takes a few seconds; ask for little or no text in it, since generated text is often misspelled.
kind="gif": pass timestamp (start) and duration (seconds). Captures a short GIF clip from the base video. Requires the project to have a video clip. A GIF still rendering after ~20s returns status: "processing" and a job_id: it is added to the article when ready (follow it with get_media_job).

Input Schema

Name	Required	Description
`kind`	Yes	'image' or 'gif'.
`after`	No	Put it right after the block holding this screenshot_id, or 'start' / 'end' (the default).
`prompt`	No	kind='image' only: generate an AI illustration from this prompt instead of capturing or attaching one.
`replace`	No	Put it in place of this screenshot_id, wherever that sits; the old one is removed from the article.
`duration`	No	kind='gif' only: GIF duration in seconds.
`style_id`	No	kind='image' with prompt only: an image style pack ID from find(type='image_gen_style_packs').
`timestamp`	No	kind='image': capture frame at this timestamp (seconds). kind='gif': GIF start time.
`project_id`	Yes	Project ID.
`source_url`	No	kind='image' only: an https image URL to download and attach.
`aspect_ratio`	No	kind='image' with prompt only: the illustration's shape. Default 16:9.
`mcp_upload_id`	No	kind='image' only: attach an uploaded image (mcp_upload_id from upload_file, or a Clueso upload_id) instead of capturing from video.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 28, 2026

addedInput schema / properties / after

Added value: +{
+  "description": "Put it right after the block holding this screenshot_id, or 'start' / 'end' (the default).",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / aspect_ratio

Added value: +{
+  "description": "kind='image' with prompt only: the illustration's shape. Default 16:9.",
+  "enum": [
+    "16:9",
+    "1:1",
+    "4:3",
+    "3:4",
+    "9:16",
+    "21:9"
+  ],
+  "type": "string"
+}

addedInput schema / properties / prompt

Added value: +{
+  "description": "kind='image' only: generate an AI illustration from this prompt instead of capturing or attaching one.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / replace

Added value: +{
+  "description": "Put it in place of this screenshot_id, wherever that sits; the old one is removed from the article.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / style_id

Added value: +{
+  "description": "kind='image' with prompt only: an image style pack ID from find(type='image_gen_style_packs').",
+  "type": "string"
+}

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / mcp_upload_id / description

Previous value: -"kind='image' only: attach an uploaded image (mcp_upload_id from the upload tool) instead of capturing from video."New value: +"kind='image' only: attach an uploaded image (mcp_upload_id from upload_file, or a Clueso upload_id) instead of capturing from video."

addedInput schema / properties / source_url

Added value: +{
+  "description": "kind='image' only: an https image URL to download and attach.",
+  "format": "uri",
+  "type": "string"
+}

Changed4 schema fields changedSep 22, 2026

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"
-}

removedInput schema / properties / conversation_id

Removed value: -{
-  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
-  "type": "string"
-}

removedInput schema / properties / llm_model

Removed value: -{
-  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "kind",
-  "project_id",
-  "context",
-  "llm_model"
-]New value: +[
+  "kind",
+  "project_id"
+]

Changed4 schema fields changedSep 22, 2026

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"
+}

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
+  "type": "string"
+}

addedInput schema / properties / llm_model

Added value: +{
+  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "kind",
-  "project_id"
-]New value: +[
+  "kind",
+  "project_id",
+  "context",
+  "llm_model"
+]

Changed2 schema fields changedSep 17, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

First observedAug 11, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (which only declare non-read-only, non-destructive, open-world), the description discloses cost (generated images consume AI credits "like generate_media's"), latency ("takes a few seconds"), and a full async contract: a GIF still rendering after ~20s returns `status: "processing"` plus a `job_id` and lands in the article later. It also discloses that `replace` removes the old screenshot and states exactly what is returned (`screenshot_id` and the new `article_version`).

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?

Structure is strong: a front-loaded sentence covering placement and return values, then two scannable bullets keyed by `kind`. It is slightly long and repeats a few facts already present in the schema property descriptions (style_id/aspect_ratio applicability, aspect_ratio default), which keeps it off 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?

With 11 parameters, no output schema, and a mix of sync/async behavior, the description covers everything needed to call correctly: placement precedence, per-kind required params, the video-clip precondition, credit cost, and the async job fallback with its follow-up tool. Return values are described inline, compensating for the missing output schema.

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 earns above that by documenting cross-parameter conditionals the schema lists only per-field (`prompt` interaction with `style_id`/`aspect_ratio`, default 16:9), the origin of opaque IDs (`mup_…` from upload_file vs a Clueso upload_id), and practical guidance that generated text is often misspelled. Some of this duplicates the schema text rather than adding new meaning.

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 ("Add a screenshot or GIF to the article") and immediately explains the three mutually exclusive placement modes (`after`, `replace`, otherwise append). It is clear what the tool does, but it never contrasts itself with the closely related sibling `update_article_media`, leaving the add-vs-modify decision to inference.

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?

Usage is spelled out per mode: `kind="image"` lists all four capture/attach/generate sources and when each applies, `kind="gif"` states the required `timestamp`+`duration` and the precondition that the project must have a video clip. It also routes the agent to the right companions for adjacent steps (`upload_file` for `mcp_upload_id`, `generate_media` for `source_url`, `find(type='image_gen_style_packs')` for `style_id`, `get_media_job` to follow a pending job).

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

All Clueso tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Add article media (image or GIF)

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources