Skip to main content
Glama

find_packaging

Find packaging: the titles and thumbnails that earned the click on a topic, from long-form YouTube videos that beat their own channel.

What it does: runs the same outlier search as find_long_hooks (long-form YouTube,
2023 or later, views at least min_outlier times the channel's usual), then looks at
each video's thumbnail beside its title and says what the pair is doing.

What comes back: the run's `finds`, ranked. Each is a real package, as YouTube shows
it: title (verbatim) and thumbnail_url (the size YouTube really served, the picture
the analysis looked at; thumbnail_checked says so), channel, watch_url, views,
channel_median_views, outlier, outlier_score (0 to 100 on one fixed scale, so finds
from different runs rank together), outlier_tier, channel_size and posted_at, plus the analysis: title_device (curiosity_gap, contrarian_claim,
specific_number, how_to, listicle, challenge, story, question, warning, comparison,
authority, timeliness, identity_callout, other), title_template (the title as a
fill-in structure), thumbnail_text (the words printed on the thumbnail, read by a vision
model; null when none), thumbnail_text_role (repeats_title, adds_to_title,
contrasts_title, no_text; counted from title_overlap, the share of the thumbnail's words
that are also in the title, where that can be), thumbnail_subject, thumbnail_faces,
thumbnail_emotion,
thumbnail_colors, thumbnail_composition, thumbnail_devices, angle, gap (what the picture shows that the title does not say, and the
question that leaves), promise, steal_it and audience, plus cut_on_phone (the title is
longer than 60 characters, where a phone roughly cuts it; approximate) and on_subject
(yes or partly: whether the look judged the package to be about your topic; a package
judged not to be is dropped and the next one takes its slot; null on a link run). analysed
is false when a package could not be looked at (its look is asked twice, and the next
candidate takes the slot if it fails twice); it is still a real package.

The run's report then holds title_patterns and thumbnail_patterns (what at least two
of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by
default, 0 for none) packages WRITTEN for your topic from those patterns, each a title
a thumbnail concept and thumbnail_text (the words to print on it), naming the real
packages it is based_on. report.ideas_label is always "Written by Hook Detector from
the patterns in these real packages": show it with them, never present an idea as a
real video's title; an idea over 70 characters, with more than 5 words for its
thumbnail or repeating a real title is dropped. report.numbers counts the packages:
title_chars and title_words
(medians), titles_with_number, titles_with_question, titles_cut_on_phone (with
phone_title_chars, the approximate length a phone cuts a title at), thumbnails_with_text
and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and
emotions that repeat (name, count); age_cohorts repeats the counts for packages posted in
the last split_days days (recent) and for older ones, with the undated apart.
report.landscape is the subject at a glance, as on find_long_hooks.

Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube
address exactly as on find_long_hooks (a channel's own outliers, or that one video; no
ideas are written for a link, use remix_find); count 1 to 30 (default 12); language,
country, min_outlier, posted_within_days, channel_size and reuse as on
find_long_hooks; idempotency_key and wait_seconds as on find_hooks.

Cost: reserves up to 70 credits for 24 packages or fewer and 3 more for each package
above that (88 at 30; down to 25) and charges only the provider calls it
made: the searches, one call per channel measured, and one for each video whose date
had to be read exactly. Looking at a thumbnail costs no credit. After a find_long_hooks run on the same topic it is close
to free. A failed run costs nothing, and so does a run that finds nothing, inside the
allowance.

Timing and next step: how long a run takes has not been measured yet, so never assume
a time. Call get_run with wait_seconds=50 until status is done or failed;
progress.items holds the packages looked at so far as cards and progress.scan the videos
it is looking at while it runs. Same as POST /v1/packaging. Needs the research
permission.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNohow many packages to deliver, 1 to 30
ideasNooptional, 0 to 10 (default 6): how many written packages (a title and a thumbnail concept) to add for the subject; 0 for none
reuseNostart from the videos your last long or packaging run on this topic already bought (within a week), so the second tab on a topic costs little
topicYesthe subject to research, 3 to 500 characters, in any language. Or a YouTube address instead of a subject: a channel's (https://www.youtube.com/@name, or just @name) returns that channel's own outliers, its recent long-form uploads that beat its usual; a long-form video's (https://www.youtube.com/watch?v=...) returns that one video, whatever its multiple. A Short's address is refused (422)
api_keyNo
countryNooptional, an assigned ISO 3166-1 alpha-2 code (US, GB, MA): searches YouTube as seen from this country. It steers the search; it does not filter the channels
languageNooptional, up to 60 characters: the language the videos should be spoken in, in words or as a tag ("Spanish", "pt-BR"). Left out, it is read from the topic's own language
min_outlierNooptional, 1.5 to 100 (default 2): how many times its own channel's usual views a video must have to count as an outlier. Only outliers are ever delivered
channel_sizeNooptional: only videos from channels of this size, by what the channel's uploads usually get (its median views, the figure the outlier is measured against): small (under 20,000), medium (up to 200,000) or large. Null or left out: any size
wait_secondsNo0 to 50: seconds to wait for the run to finish; 0 returns at once
idempotency_keyNo1 to 255 visible ASCII characters; the same key within 24 hours returns the first run instead of paying for a second
posted_within_daysNooptional, how recent the videos must be, as days: 30, 90, 365, 730. Null or left out means everything since 2023-01-01; nothing older is ever delivered

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / count / description
      Previous value: -"how many packages to deliver, 1 to 24"New value: +"how many packages to deliver, 1 to 30"
    • changedInput schema / properties / count / maximum
      Previous value: -24New value: +30
  2. Added

TDQS

A4.3/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden and does so thoroughly: it discloses cost mechanics (up to 70 credits for ≤24 packages, +3 each above, down to 25; failed/empty runs free), the research-permission requirement, idempotency behavior, progress reporting via progress.items/progress.scan, and that timing is unmeasured so no time should be assumed. It also explains drop/retry semantics for unanalysed packages and that thumbnail inspection costs no credit.

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?

Purpose is front-loaded and the prose is organized into labeled sections, which helps. But it is heavily bloated: the 'What comes back' block enumerates dozens of return fields in prose even though an output schema exists, making it far longer than necessary for an agent that already receives structured output.

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?

Given a 12-parameter async job with credit costs and a research-permission requirement, the description covers everything an agent needs: cost, timing guidance, polling via get_run with wait_seconds, progress fields, permission needs, and error/refusal cases. It is arguably over-complete, which is not a completeness gap.

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 92%, so the schema already documents nearly every parameter; the description mostly restates the same bounds ('count 1 to 30', 'topic 3 to 500 characters') and defers others to find_long_hooks. It adds marginal framing (topic may be a channel or video address, Shorts refused with 422) but does not meaningfully extend beyond the schema, so the baseline 3 applies.

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 ('Find packaging: the titles and thumbnails that earned the click') and scopes it to long-form YouTube videos that beat their channel. It explicitly differentiates from its closest sibling by noting it 'runs the same outlier search as find_long_hooks' and then adds the thumbnail/title analysis, so an agent can distinguish the two 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 Guidelines4/5

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

Gives clear context: it reuses the find_long_hooks search, is 'close to free' after a find_long_hooks run on the same topic, and routes link-based runs to remix_find. However it never states an explicit when-to-use-this-instead-of-find_long_hooks condition beyond the implicit 'you want thumbnail+title analysis', so it stops short of a full when/when-not/alternative statement.

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.

Resources