hooklayer

search_videos

Idempotent

Search for short-form videos by keyword across TikTok or Instagram. Returns up to 20 videos ranked by engagement, with view counts, likes, shares, comments, hashtags, author info, and URLs. Use when the user asks to find videos about a topic or keyword. Supports optional filters for niche, minimum views, recency window, and region. Pass product_id to check which videos link a specific TikTok Shop product: linkage is exact_product_link only when the video carries that product link; keyword_match videos are NOT verified for that product, and evidence_summary.product_linkage.status is VIDEO_LINKAGE_UNVERIFIED when none link it. Region counts as verified only from the provider-reported video region; otherwise it is unknown. View counts are cumulative and do not show current acceleration.

Input Schema

Name	Required	Description
`limit`	No	Max videos to return after filtering. Default 12, max 20.
`niche`	No	Optional — only return videos whose description contains niche-related tokens. Loose niche strings work ("fitness", "Beauty & Skincare").
`query`	Yes	Free-text search term. Examples: "morning routine", "iphone case", "passive income".
`region`	No	ISO country code (US, GB, BR, PH, JP, etc.). Note: corpus coverage varies by region — small regions may return zero results and a degraded quality flag.
`window`	No	Recency filter. Maps to the closest ScrapeCreators date bucket AND applies a client-side cutoff for defense-in-depth.
`platform`	No	Which platform to search. "tiktok" (default) hits ScrapeCreators TikTok keyword search. "instagram" (2026-07-06) hits Instagram Reels search — note IG upstream ignores region/date_posted params, so region enforcement is client-side only (region_verified_count in the response tells you how many results verifiably matched).
`min_views`	No	Optional view-count floor. Default 0.
`product_id`	No	Optional TikTok Shop product id. Videos that link this exact product are labelled exact_product_link and listed first; all others stay keyword_match (not verified for this product).

Output Schema

Name	Required	Description
`videos`	No
`applied`	No	Echo of the filters actually applied — useful for debugging when results look surprising
`quality`	No
`from_payg`	No
`filtered_count`	No	Videos returned after filtering + cap
`upstream_count`	No	Videos returned by upstream before any filtering
`evidence_summary`	No	Unique creators, creator concentration, posted-date range, duplicates removed, region evidence counts and product_linkage {status: VERIFIED \| VIDEO_LINKAGE_UNVERIFIED \| NOT_REQUESTED}.
`credits_remaining`	No	Credits remaining after this call
`from_subscription`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 14, 2026

addedInput schema / properties / product_id

Added value: +{
+  "description": "Optional TikTok Shop product id. Videos that link this exact product are labelled exact_product_link and listed first; all others stay keyword_match (not verified for this product).",
+  "pattern": "^[0-9]{10,25}$",
+  "type": "string"
+}

addedOutput schema / properties / evidence_summary

Added value: +{
+  "description": "Unique creators, creator concentration, posted-date range, duplicates removed, region evidence counts and product_linkage {status: VERIFIED | VIDEO_LINKAGE_UNVERIFIED | NOT_REQUESTED}.",
+  "type": [
+    "object",
+    "null"
+  ]
+}

addedOutput schema / properties / videos / items / properties / is_ad
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / videos / items / properties / is_paid_partnership
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / videos / items / properties / linkage

Added value: +{
+  "enum": [
+    "exact_product_link",
+    "product_link_other",
+    "keyword_match"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / videos / items / properties / linked_product_id

Added value: +{
+  "description": "TikTok Shop product the video links, if any",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / videos / items / properties / linked_product_url
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

addedOutput schema / properties / videos / items / properties / provider_region

Added value: +{
+  "description": "Region the provider attached to the video; null = unknown",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / videos / items / properties / region_evidence

Added value: +{
+  "enum": [
+    "provider_reported_match",
+    "text_signal",
+    "unknown"
+  ],
+  "type": "string"
+}

Changed1 schema field changedJul 7, 2026

addedInput schema / properties / platform

Added value: +{
+  "description": "Which platform to search. \"tiktok\" (default) hits ScrapeCreators TikTok keyword search. \"instagram\" (2026-07-06) hits Instagram Reels search — note IG upstream ignores region/date_posted params, so region enforcement is client-side only (region_verified_count in the response tells you how many results verifiably matched).",
+  "enum": [
+    "tiktok",
+    "instagram"
+  ],
+  "type": "string"
+}

AddedJun 10, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Goes well beyond annotations by disclosing the 20-result cap, engagement ranking, exact_product_link vs keyword_match linkage semantics, VIDEO_LINKAGE_UNVERIFIED status, region-verification rules, and that view counts are cumulative (no acceleration). These are non-obvious behavioral traits an agent needs. Minor gap: annotations carry readOnlyHint=false, which is unusual for a search tool, and the description does not reconcile or mention any side effects.

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?

Front-loaded with what it does, then usage, then caveats — a sensible ordering. It is dense and long-ish, but each clause (linkage rules, region verification, cumulative views) earns its place as non-obvious caveats rather than filler.

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 an 8-parameter search tool with an output schema and annotations, the description covers purpose, usage, filtering, and the tricky product-linkage and region-verification semantics. Return-value detail is delegated to the output schema, which is appropriate. Nothing critical to correct invocation is missing.

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 baseline is 3, but the description adds real meaning beyond the schema: product_id linkage semantics and the region-verified vs unknown distinction, which are not in the parameter descriptions. It stops short of value-format guidance (e.g., how to phrase niche or region).

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 (search) and resource (short-form videos) with scope (keyword, TikTok/Instagram) and output shape (up to 20 ranked by engagement). No sibling tool performs video keyword search, so it is cleanly differentiated from trend_pulse, find_viral_template, etc.

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?

Explicitly says 'Use when the user asks to find videos about a topic or keyword,' which gives a clear triggering condition. It does not name alternatives or when-not-to-use, but the sibling set covers other task types rather than competing searches.

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

All hooklayer tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.