hooklayer

find_viral_template

Idempotent

Find proven viral templates in a niche with example videos. Returns templates ranked by performance, including hook patterns, format structures, average views, and example URLs. Use when the user asks what's working in a niche or wants concrete copyable structures. Supports the 18 canonical niches with optional angle narrowing via query parameter for more specific results (e.g., "postpartum strength" within Fitness).

Input Schema

TableJSON Schema

Name	Required	Description
`niche`	Yes	One of the 18 supported niches (Beauty & Skincare, Fitness & Health, Food & Cooking, Fashion & Style, Tech & Gadgets, Finance & Business, Education & Learning, Travel & Adventure, Comedy & Entertainment, Gaming, Lifestyle & Wellness, Parenting & Family, DIY & Crafts, Music & Dance, Pets & Animals, Sports, Motivation & Self-Help, SaaS & AI Tools). Loose names like "travel" or "fitness" are accepted but pass the canonical form when possible.
`query`	No	Optional angle narrowing within the niche. E.g. niche="Fitness & Health" + query="postpartum strength" returns only postpartum-strength templates, not generic gym. Templates are scored by query-token match against title+description+hashtags; zero-match templates are dropped. Leave empty for niche-wide top templates.
`region`	No	Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to YouTube Search regionCode + TikTok niche query. Reddit niche signals are global and ignore this param. Pass when the user wants templates that resonate with a specific local audience.
`window`	No	Recency filter. Drops example videos older than the window. Note: TikTok hashtag-corpus rows often lack timestamps and are excluded when window is set — surfaces as a quality warning so callers can decide whether to broaden.
`platform`	No	Platform to source templates from. "tiktok" (default) uses the full niche-aggregator (YouTube + Reddit + TikTok hashtags). "instagram" (2026-07-06) is keyword-search-only — the Instagram niche-aggregator isn't plumbed yet, so `query` becomes REQUIRED on IG. Output rubric_version signals which path ran: find_viral_template.v1 (main), .v2-keyword-fallback (TikTok fallback), .v3-instagram-keyword-only (IG-only path).
`min_views`	No	Optional filter — only return examples above this view count

Output Schema

TableJSON Schema

Name	Required	Description
`niche`	No	The niche searched
`from_payg`	No	Whether credits came from pay-as-you-go balance
`templates`	No	Ranked viral templates with hook patterns and example URLs
`credits_remaining`	No	Credits remaining after this call
`from_subscription`	No	Whether credits came from subscription

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 4, 2026

changedInput schema / properties / niche / description

Previous value: -"One of the 17 supported niches. Loose names like \"travel\" or \"fitness\" are accepted but pass the canonical form when possible."New value: +"One of the 18 supported niches (Beauty & Skincare, Fitness & Health, Food & Cooking, Fashion & Style, Tech & Gadgets, Finance & Business, Education & Learning, Travel & Adventure, Comedy & Entertainment, Gaming, Lifestyle & Wellness, Parenting & Family, DIY & Crafts, Music & Dance, Pets & Animals, Sports, Motivation & Self-Help, SaaS & AI Tools). Loose names like \"travel\" or \"fitness\" are accepted but pass the canonical form when possible."

Changed1 schema field changedJul 7, 2026

addedInput schema / properties / platform

Added value: +{
+  "description": "Platform to source templates from. \"tiktok\" (default) uses the full niche-aggregator (YouTube + Reddit + TikTok hashtags). \"instagram\" (2026-07-06) is keyword-search-only — the Instagram niche-aggregator isn't plumbed yet, so `query` becomes REQUIRED on IG. Output rubric_version signals which path ran: find_viral_template.v1 (main), .v2-keyword-fallback (TikTok fallback), .v3-instagram-keyword-only (IG-only path).",
+  "enum": [
+    "tiktok",
+    "instagram"
+  ],
+  "type": "string"
+}

Changed1 schema field changedJun 30, 2026

addedInput schema / properties / query

Added value: +{
+  "description": "Optional angle narrowing within the niche. E.g. niche=\"Fitness & Health\" + query=\"postpartum strength\" returns only postpartum-strength templates, not generic gym. Templates are scored by query-token match against title+description+hashtags; zero-match templates are dropped. Leave empty for niche-wide top templates.",
+  "type": "string"
+}

Changed1 schema field changedJun 10, 2026

changedInput schema / properties / niche / enum

Previous value: -[
-  "Beauty & Skincare",
-  "Fitness & Health",
-  "Food & Cooking",
-  "Fashion & Style",
-  "Tech & Gadgets",
-  "Finance & Business",
-  "Education & Learning",
-  "Travel & Adventure",
-  "Comedy & Entertainment",
-  "Gaming",
-  "Lifestyle & Wellness",
-  "Parenting & Family",
-  "DIY & Crafts",
-  "Music & Dance",
-  "Pets & Animals",
-  "Sports",
-  "Motivation & Self-Help"
-]New value: +[
+  "Beauty & Skincare",
+  "Fitness & Health",
+  "Food & Cooking",
+  "Fashion & Style",
+  "Tech & Gadgets",
+  "Finance & Business",
+  "Education & Learning",
+  "Travel & Adventure",
+  "Comedy & Entertainment",
+  "Gaming",
+  "Lifestyle & Wellness",
+  "Parenting & Family",
+  "DIY & Crafts",
+  "Music & Dance",
+  "Pets & Animals",
+  "Sports",
+  "Motivation & Self-Help",
+  "SaaS & AI Tools"
+]

Changed2 schema fields changedJun 10, 2026

addedInput schema / properties / region

Added value: +{
+  "description": "Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to YouTube Search regionCode + TikTok niche query. Reddit niche signals are global and ignore this param. Pass when the user wants templates that resonate with a specific local audience.",
+  "type": "string"
+}

addedInput schema / properties / window

Added value: +{
+  "description": "Recency filter. Drops example videos older than the window. Note: TikTok hashtag-corpus rows often lack timestamps and are excluded when window is set — surfaces as a quality warning so callers can decide whether to broaden.",
+  "enum": [
+    "24h",
+    "7d",
+    "30d",
+    "90d",
+    "this-month"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedMay 23, 2026

changedInput schema / properties / niche / description

Previous value: -"Niche to search (e.g. \"Beauty & Skincare\")"New value: +"One of the 17 supported niches. Loose names like \"travel\" or \"fitness\" are accepted but pass the canonical form when possible."

addedInput schema / properties / niche / enum

Added value: +[
+  "Beauty & Skincare",
+  "Fitness & Health",
+  "Food & Cooking",
+  "Fashion & Style",
+  "Tech & Gadgets",
+  "Finance & Business",
+  "Education & Learning",
+  "Travel & Adventure",
+  "Comedy & Entertainment",
+  "Gaming",
+  "Lifestyle & Wellness",
+  "Parenting & Family",
+  "DIY & Crafts",
+  "Music & Dance",
+  "Pets & Animals",
+  "Sports",
+  "Motivation & Self-Help"
+]

Changed1 schema field changedMay 14, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "credits_remaining": {
+      "description": "Credits remaining after this call",
+      "type": "number"
+    },
+    "from_payg": {
+      "description": "Whether credits came from pay-as-you-go balance",
+      "type": "boolean"
+    },
+    "from_subscription": {
+      "description": "Whether credits came from subscription",
+      "type": "boolean"
+    },
+    "niche": {
+      "description": "The niche searched",
+      "type": "string"
+    },
+    "templates": {
+      "description": "Ranked viral templates with hook patterns and example URLs",
+      "items": {
+        "properties": {
+          "avg_views": {
+            "type": "number"
+          },
+          "format": {
+            "type": "string"
+          },
+          "hook_pattern": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

First observedMay 14, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare openWorldHint, idempotentHint, and readOnlyHint=false, so the safety profile is partly covered. The description adds that results are ranked by performance, but it does not explain why a pure 'find' operation carries readOnlyHint=false, nor does it surface the platform/fallback behavior that lives only in the schema. With annotations present, a 3 reflects modest added context.

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?

Three sentences, front-loaded with the core purpose before usage and parameter notes. No filler, though the final sentence's parameter detail is somewhat redundant with the schema.

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, rich annotations, and 100% schema coverage, the description need only convey purpose and routing, which it does. Nothing critical is missing for an agent to invoke it correctly.

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 100%, so every parameter (niche, query, region, window, platform, min_views) is already documented in the schema. The description restates the query-narrowing and 18-niche concepts already covered there, adding no new semantics, so baseline 3 applies.

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?

States a specific verb and resource ('Find proven viral templates in a niche with example videos') and describes the ranked-by-performance output with hook patterns and example URLs, which is distinct from generic search siblings like search_videos or trend_pulse. It does not explicitly name which sibling to prefer, so it stops short of a 5.

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 triggering context ('Use when the user asks what's working in a niche or wants concrete copyable structures'), which tells the agent when this tool fits. It offers no explicit when-not conditions or named alternatives among siblings, so it lacks the exclusion guidance a 5 would require.

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.