Clipwright

Analyse a reference ad

analyze_reference

Idempotent

Analyze a reference video or Instagram/TikTok link to extract beats, transcript, graphics, pacing, palette and music into a reusable profile; data mode returns duration, transcript and frame sheet.

Instructions

Read a reference ad into a reference_profile: its beats (role, timing as shares of the clip, whether the presenter speaks, listens or is off screen), the graphics in our template vocabulary, captions, pacing, palette and music. It keeps the reference's words: transcript (timed words), hook (the words of its first 3 s, through the end of that sentence), each beat's spoken_summary and each graphic's label_hint. What we cannot draw is in unmapped with a substitute and in warnings. Pass asset_id of an MP4 asset (create_asset with kind: "video"), at most 120 s and 100 MiB, or source_url: an Instagram reel or post link (instagram.com/reel/, /reels/, /p/) or a TikTok video link (tiktok.com/@/video/, vm.tiktok.com/). A link becomes an analysis-only asset of this account (asset_id in the answer) and the answer's source carries the post's views, likes, comments, views per hour, the author's median views around it and over their 12 latest reels, each with the ratio, the top comments and the code words commenters repeat; a number the platform did not give is null and named in warnings. A YouTube link is refused: upload its MP4 with create_asset. mode: "data" skips the vision pass and answers data instead of a profile: duration, size and fps, the timed transcript, the hook and a 3×3 frame sheet (a signed JPEG link), with source for a link as above; a reel with no speech gives an empty transcript and a warning. 70 credits for full, 10 for data, held at the start and charged once it succeeds; a failed analysis costs nothing. 10 new full and 60 new data analyses per hour per account. Answers at once with state queued; call get_reference_analysis every 10 seconds until succeeded (about a minute) or failed. The same asset, or the same reel by its full link, in the same mode returns the same analysis, free, unless it failed; a short vm.tiktok.com link always starts a new one. The asset is not changed. The profile names techniques; it copies no face, voice, music or brand of the reference. Price: 70 credits per call; data mode: 10 credits per call. Quote first with quote_analysis; list_prices names every price.

Input Schema

Name	Required	Description
`mode`	No	full (default, 70 credits): the reference_profile. data (10 credits): duration, size, timed transcript, hook and a 3×3 frame sheet, without the vision pass
`asset_id`	No	asset_id of an MP4 asset of this account, at most 120 s and 100 MiB
`source_url`	No	instead of asset_id: an Instagram reel or post link (instagram.com/reel/<code>, /reels/<code>, /p/<code>) or a TikTok video link (tiktok.com/@<user>/video/<id>, vm.tiktok.com/<code>); YouTube is refused

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.36.0Oct 31, 2026

addedInput schema / properties / mode

Added value: +{
+  "description": "full (default, 70 credits): the reference_profile. data (10 credits): duration, size, timed transcript, hook and a 3×3 frame sheet, without the vision pass",
+  "enum": [
+    "full",
+    "data"
+  ],
+  "type": "string"
+}

addedInput schema / properties / source_url

Added value: +{
+  "description": "instead of asset_id: an Instagram reel or post link (instagram.com/reel/<code>, /reels/<code>, /p/<code>) or a TikTok video link (tiktok.com/@<user>/video/<id>, vm.tiktok.com/<code>); YouTube is refused",
+  "format": "starts_with",
+  "maxLength": 2048,
+  "pattern": "^https:\\/\\/.*",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "asset_id"
-]
```

Addedv0.35.0Oct 30, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only mark it non-readonly and idempotent; the description goes far beyond by disclosing credit hold/charge semantics (70/10, failed analysis free), per-hour rate limits (10 full / 60 data), the async contract (answers 'queued', poll every 10 s, ~1 minute), and the caching rule including the vm.tiktok.com exception. It also states the asset itself is not mutated, which reconciles readOnlyHint=false with destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and dense with useful facts, but the pricing line is stated twice (mode description plus a closing 'Price: 70 credits per call; data mode: 10 credits per call'), and the source_url formats are repeated in the same sentence structure as the schema. The single block paragraph also makes it harder to scan than it needs to be.

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 high-cost, async, quota-limited analysis tool with no output schema, the description supplies everything an agent needs: inputs and their limits, the async polling loop, cost and quota behavior, idempotency/caching rules, and what the answer contains in each mode. Nothing consequential about correct invocation is left unstated.

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, but the description adds genuine meaning beyond the schema: the 120 s / 100 MiB limits, the exact link shapes accepted, that a link becomes an analysis-only asset of this account with its asset_id returned, and what mode 'data' produces. Only marginal detail (e.g. that no parameter is required and the default is 'full') duplicates the 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?

Opening sentence gives a specific verb and resource ('Read a reference ad into a reference_profile') and immediately enumerates the concrete contents of that profile (beats, graphics, captions, pacing, palette, music). It is clearly distinguishable from siblings like quote_analysis (pricing), get_reference_analysis (polling) and plan_reference_remake (downstream use).

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?

Explicitly names the alternative paths: use create_asset to upload a YouTube MP4 because a YouTube link is refused, quote_analysis to price first, and get_reference_analysis to poll. It also states which input to supply (asset_id vs source_url) and the two mode choices, with the credit cost of each.

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

Analyse a reference ad

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools