hooklayer

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

Beyond annotations (readOnly, idempotent), the description adds valuable behavioral details: returns empty + warning with no credits charged on zero matches, Transcript behavior on YouTube/Instagram, and Instagram's totalLikes defaulting to 0. This exceeds annotation coverage.

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

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

The description is somewhat long but well-structured: starts with purpose, enumerates outputs, then provides usage guidance and platform-specific caveats. Each sentence adds value, though it could be trimmed without losing core information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multi-platform, transcripts, edge cases), the description covers all necessary context: platforms supported, output details, filter behavior, and platform-specific limitations. Output schema and annotations further reduce gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides 100% parameter descriptions, including examples and 'use either since or window, not both' constraint. The tool description offers no additional parameter-specific semantics beyond contextualizing platform behavior, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes a creator by handle or platform, specifically naming TikTok, YouTube, and Instagram. It lists concrete outputs (viral DNA scores, content patterns, transcripts) that distinguish it from sibling tools like search_videos or predict_virality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly says 'Use when the user asks to analyze a creator, account, channel, or competitor,' giving a clear trigger. It does not mention exclusions or contrast with sibling tools, but the use case is well-scoped.

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

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

Beyond annotations declaring readOnlyHint=true and destructiveHint=false, the description adds critical behavioral context: it costs 7 credits, composes upstream tools, and details when the output is a 'starting point rather than a shippable direction' (if quality.level is not 'full' or verdict is NEEDS_MORE_DATA/NO_GO). This substantially informs the agent about expected behavior and limitations.

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

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

The description is lengthy but information-dense, covering purpose, use case, composition, cost, and detailed return semantics. It is front-loaded with the core purpose and every sentence serves a functional role. Slightly longer than the minimal necessary, but justified for a tool of this complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool chaining four upstream tools with 7 parameters and a rich output, the description is remarkably complete. It explains the output object's key fields, the verdict semantics, trend_still_alive statuses, and the conditions under which the result isn't shippable. The presence of an output schema reduces the burden, but the description goes beyond what the schema would provide.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with detailed per-parameter explanations (e.g., platform context, deadline_hours effect, creator_handle recommendation). The description itself adds no per-parameter detail beyond the schema, so the baseline score of 3 applies; it neither enhances nor detracts from the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Turn a brand brief that just landed into a one-page creative blueprint...' and lists concrete output components (hook, template, hashtag combo, trend-velocity check, shoot instructions). It clearly distinguishes itself from sibling tools by stating it chains find_viral_template, trend_pulse, score_hook, and predict_virality into one composite tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit when-to-use guidance is given: 'Use when a brand sends a product and needs content on a tight turnaround (e.g. product arrived, need content in 48 hours)' and 'the manager needs a defensible direction with no research time.' It also names the alternative of stitching the upstream chain manually, implying this tool replaces that manual process.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds useful context about return content (ranked by performance, hook patterns) and query narrowing. It does not disclose platform-specific fallback behaviors (Instagram keyword-only, TikTok timestamp caveats), which are left to the schema.

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

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

Four sentences, front-loaded with purpose, followed by return details, usage guidance, and a capacity note. Every sentence earns its place, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema and output schema, the description adequately covers the core function and usage. It doesn't compare with siblings, and there is a minor niche-count discrepancy ('17' vs 18 enum entries), but the overall context is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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's mention of query angle narrowing adds no new semantics beyond what the schema already provides with its own example. The schema carries the parameter explanation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Find proven viral templates in a niche with example videos.' It clearly states what the tool does and what it returns (templates ranked by performance, hook patterns, etc.), distinguishing it from siblings like search_videos or trend_pulse.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit usage context is provided: 'Use when the user asks what's working in a niche or wants concrete copyable structures.' This gives clear guidance, though it lacks explicit when-not-to-use or alternative tool comparisons.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the burden. The description adds meaningful behavioral context: requires at least 3 reference samples, returns a voice profile and reusable prompt instructions. No contradiction; it does not disclose edge cases or auth, but the annotation coverage makes this acceptable.

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

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

Three sentences, front-loaded with the core function, followed by requirements and use case. Every sentence earns its place, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description is sufficient for typical use. It covers inputs, requirements, outputs, and intended use case. Lacking explicit exclusions or alternative guidance, but not necessary given the schema richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters (draft and reference_samples) are well documented in the schema. The description adds reinforcing details like 'at least 3' and 'video URLs or text' but does not significantly expand beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource: 'Extract a creator's voice DNA from reference samples and rewrite a draft in their style.' It clearly distinguishes this tool from siblings like analyze_account or viral_remix by focusing on style transfer and voice matching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states when to use: 'Use when the user wants to write in another creator's style or match a specific voice.' It does not name alternatives or exclusions, but the context is clear enough that an agent can select it appropriately.

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

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

Adds behavior beyond annotations: 'adversarial verification' and 'attack vectors analysis' signal a critical evaluation style, and 'auto-extracts transcript' for video URLs. Annotations already cover readOnly/idempotent/destructive safety, so this extra context earns a 4.

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

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

Three sentences with no filler: function, outputs, usage, and input format. Front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema covers returns; description adds use case, input variants, and output summary. Given annotations and schema, no meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. Description repeats the script/URL option already in the schema and doesn't explore 'niche' semantics, adding little beyond structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Score' + resource 'draft script for viral potential' with adversarial verification; clearly separates it from sibling tools like score_hook by targeting finished drafts for pre-publish verification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states 'Use when the user has a finished draft and wants pre-publish verification.' This gives clear context but doesn't enumerate when to avoid or name alternatives, so not a 5.

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

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

With annotations already declaring readOnlyHint=true, idempotent, and non-destructive, the description adds value by detailing what the tool does: returns a score, percentile, matched pattern, strengths/weaknesses, and variations. It also notes that platform affects pattern matching, giving useful behavioral context beyond the annotations. No contradictions found.

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

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

The description is two sentences, front-loaded with the core purpose in the first sentence, and the second sentence covers returns and use cases. Every word earns its place; no redundant or vague phrasing. It is compact yet informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for the tool's complexity. It explains the purpose, return value, and when to use it. The output schema (not shown but present) handles detailed return structure, so the description need not over-explain. Annotations cover safety behavior, and the schema covers parameters. No major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter having its own description (e.g., 'The hook to score', 'Optional niche context', 'Target platform — affects pattern matching'). The tool description adds a bit of context about patterns and variations but does not significantly enhance the schema's parameter explanations. A baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Score a TikTok, Reels, or Shorts hook') and a specific resource ('against proven viral patterns'). It also lists concrete outputs (0-100 score, percentile rank, pattern, strengths/weaknesses, variations), distinguishing it from sibling tools like predict_virality or viral_remix. The verb 'score' is unambiguous and not a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description includes explicit use cases: 'Use when the user has a draft hook to validate, wants to compare alternatives, or needs feedback before publishing.' This provides clear contextual guidance. However, it does not name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by stating results are ranked by engagement and include specific metrics, beyond what annotations alone provide. No contradiction exists.

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

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

The description is concise, front-loaded with the core action, and contains only three sentences that each earn their place: purpose, output, and use case. No redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the schema fully documents all parameters and platform-specific caveats, and an output schema exists (as indicated by context), the description adequately covers the tool's purpose, use cases, and high-level output. The agent has enough information to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% parameter description coverage, including detailed notes on each parameter such as niche matching and Instagram's handling of region. The description merely summarizes these filters without adding any new semantic meaning, so it meets but does not exceed the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for short-form videos by keyword on TikTok or Instagram, and lists specific return fields like view counts, likes, shares, and URLs. This distinguishes it from sibling tools like analyze_account or score_hook, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly says 'Use when the user asks to find videos about a topic or keyword,' providing a clear trigger. However, it does not mention alternatives or exclusions, so it misses a 5.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it explains data sources, growth signals, region filtering behavior (Reddit signals ignore region), and the special deadline_hours behavior that adds trend_status and deadline_verdict fields. This is transparent and supports safe, effective usage.

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

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

The description is succinct, well-structured, and front-loaded. It captures the core purpose, use cases, and output in three sentences, with no redundant or filler content. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the annotations are rich, the description provides all necessary context: it explains what trends are returned, what types of insights (growth signals, saturated patterns), and how the deadline_hours parameter extends functionality. The tool is complex, but the description is sufficient for an agent to know when and how to place the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 adds extra meaning for the deadline_hours parameter, explaining the 'magic-genie ritual' and how it transforms outputs into actionable verdicts. It also clarifies the 17 supported niches and region behavior, going beyond the bare schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs and resources: 'Research what is currently gaining traction in short-form content for a specific niche' and 'Returns rising opportunities (formats, hooks, styles, topics) with growth signals, data sources, and saturated patterns to avoid.' This clearly distinguishes it from sibling tools like 'analyze_account' or 'score_hook', which focus on different aspects of content strategy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly states when to use the tool: 'Use when the user asks what to post about, what's trending in a niche, or needs to validate a content idea against current trends.' It does not name specific alternatives or provide when-not-to-use guidance, but the context is strong and actionable, so a small deduction is appropriate.

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

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

The description adds behavioral context beyond annotations: it details the output structure (extracted formula, script components) and explains the two input modes (auto-extraction from URL vs. faster direct transcript). This is consistent with readOnlyHint and destructiveHint=false, and no contradictions exist.

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

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

The description is four sentences, but each provides value: purpose, output, use case, and input modes. It is front-loaded and free of redundant detail, though it could be tightened slightly by merging the usage and input sentences without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description sufficiently explains the tool's purpose, outputs, and inputs. It mentions supported platforms and the alternative of passing a transcript. A minor gap is not mentioning that either source_url or transcript is required, but the anyOf schema makes this inferable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameter descriptions, so baseline is 3. The description reinforces the source_url and transcript relationship ('Pass either...') but adds no new meaning beyond what the schema already provides for niche and my_topic. Since schema coverage is high, the description does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool takes a viral video and produces a fresh script mirroring its structure, specifying the output (formula, scene-by-scene script, voiceover, visuals, camera directions, overlays). This distinguishes it from sibling tools like find_viral_template by focusing on script generation rather than just template extraction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly says 'Use when the user finds a video they want to replicate the structure of,' providing a clear trigger scenario. It also outlines input options (URL or transcript) and lists supported platforms, but does not explicitly contrast with sibling tools or mention when not to use it.

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