hooklayer

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

Beyond the annotations (idempotent, non-destructive), the description discloses several important behavioral traits: the "honest empty + warning" behavior for zero-matching filters, "no credits charged" on that path, "transcript: null" when captions are disabled/geoblocked, and Instagram's "lifetime totalLikes defaults to 0." This level of edge-case disclosure goes well beyond what annotations provide and helps the agent set accurate user expectations.

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 information-dense but well organized: action first, outputs second, usage trigger third, platform-specific behavior last. Every sentence contributes unique value, including the credit-charge warning and platform caveats. Despite its length, it is front-loaded and easy to scan, and the complexity of the tool justifies the length.

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 covers the core action, all supported platforms and their transcript availability, key output fields, usage context, and important edge cases (empty results, credit charges, platform data limitations). An output schema exists, so return values don't need to be re-explained. Nothing essential for selecting or invoking this tool is missing.

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 (handle, since, window, platform, recent_only) already thoroughly documented in the schema. The description adds high-level context—like platform transcript expectations and the since vs. window exclusivity—but for the most part it does not need to explain parameters because the schema already carries that burden. 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 opens with a specific verb and resource: "Analyze a TikTok, YouTube, or Instagram creator by handle or channel ID." It then enumerates a distinctive set of outputs (viral DNA scores, content patterns, headline_insight, etc.) that clearly separates this from sibling tools like watch_account or predict_virality. An agent can confidently identify what this tool does from the first sentence alone.

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 it: "Use when the user asks to analyze a creator, account, channel, or competitor." This is clear and actionable. However, it does not mention when not to use it or point to an alternative sibling (e.g., watch_account for ongoing monitoring), so it stops short of the full when/when-not/alternatives guidance required for 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?

Beyond the annotations, the description discloses important operational behavior: it chains multiple upstream tools, costs 7 credits with a bundle discount, and returns a quality object that tells the agent whether the result is shippable or only a starting point. This gives the agent useful expectations about side effects, cost, and reliability without contradicting the annotations.

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 long but every clause earns its place: use case, deliverable composition, chained workflow, cost, output shape, and quality caveat are all present. The most important information is front-loaded, and the output semantics are delivered as a structured, skimmable summary.

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 7 parameters, rich schema descriptions, an output schema, and a complex composite workflow, the description still covers the core deliverables, the return object, and how to interpret partial or non-GO results. It provides enough context for an agent to invoke the tool correctly and know what to do with the result.

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%, and the parameter descriptions already explain each field, including defaults, enums, and behavioral effects like deadline_hours affecting trend-still-alive scoring. The main description does not add much new parameter-level meaning beyond naming product and niche context, so the 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 names a specific verb and resource — turning a brand brief into a one-page creative blueprint — and enumerates the exact components of that blueprint (hook, template, hashtag combo, trend-velocity check, shoot instructions). It also distinguishes itself from the sibling chain tools by explaining that it bundles find_viral_template, trend_pulse, score_hook, and predict_virality into a single MCP 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?

It gives a concrete triggering scenario: a brand sends a product and needs content on a tight turnaround with little research time. It also clarifies the alternative — stitching the upstream tools manually — and why this tool exists instead, making the when-and-why decision explicit.

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 idempotentHint=true and destructiveHint=false, and the description adds that results are ranked by performance. However, operational behaviors like platform fallback paths (rubric_version) and the timestamp exclusion on TikTok rows live only in the parameter descriptions, not the main description. This keeps transparency at the baseline.

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 with the core action front-loaded. There is minor redundancy between 'example videos' in the first sentence and 'example URLs' in the second, but the length is appropriate and the 'Use when' cue is placed early enough to be useful.

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 full definition benefits from an output schema and exhaustive parameter descriptions, so an agent has the details needed to call this correctly. The description itself slightly under-serves by miscounting the niche enum (17 vs 18) and omitting the Instagram-specific requirement that query becomes mandatory, though this is documented in the schema.

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%, so the schema carries full parameter semantics. The description's example of angle narrowing ('postpartum strength' within Fitness) mirrors the query parameter's own description and adds no new information.

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 promptly enumerates the concrete outputs (hook patterns, format structures, average views, example URLs), which distinguishes it from sibling tools like search_videos or predict_virality. The only blemish is stating 17 niches while the schema enum lists 18, but this does not obscure the tool's purpose.

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?

'Use when the user asks what's working in a niche or wants concrete copyable structures' gives clear, actionable context for when to invoke the tool. It stops short of naming specific alternatives or stating when not to use it, so it misses the top score.

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 goes far beyond the annotations: it discloses that the tool runs a fresh (non-cached) analysis costing 5 credits, persists the new snapshot (mutation), returns only meaningful shifts, honestly returns status='no_meaningful_change' when nothing shifted, and returns a top_action pointing to the next tool. This paints a complete behavioral picture and aligns with the annotations (readOnly=false, idempotent=false), adding cost and state-change context the annotations don't convey.

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 longer than average but every sentence earns its place: purpose, mechanism, trigger phrases, prerequisite, cost, return behavior, and honesty note. It's front-loaded with the core purpose and mechanism, and while it could be tightened slightly, the density of useful information keeps it from feeling bloated.

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 (it runs an analysis, persists state, and returns a rich result including a top_action), the description covers all decision-relevant information: trigger phrases, prerequisites, cost, return semantics (meaningful shifts vs. no_meaningful_change), and the existence of a top_action. The output schema defines the exact return structure, so the description doesn't need to list fields. Nothing an agent needs to decide whether and how to call it is missing.

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 already documents all three parameters at 100% coverage, so the description doesn't need to re-explain them. However, it adds one valuable piece of guidance: that watch_id is preferred over (platform, handle) because the ownership check is exact. This is extra semantics that helps the agent pick the right parameter, justifying a score above the baseline 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 opens with a precise verb-resource pair ('Detect what changed since the last saved baseline for a tracked creator') and immediately differentiates it from siblings: it runs a fresh analyze_account under the hood, compares against a CreatorSnapshot, and returns only meaningful shifts. It even names the specific change categories (format, viral DNA, etc.), making the tool's purpose unmistakable and clearly distinct from analyze_account or watch_account.

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 lists trigger phrases ('what changed with @creator', 'anything new', 'check this competitor again') and states the prerequisite (a previously tracked creator, with a callout to call analyze_account + watch_account first if no baseline exists). This tells the agent exactly when to use the tool and what precondition must be met, which is strong usage guidance.

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 (readOnly, idempotent), the description reveals response fields, first-class exclusions (snapshot payload), the associated cost (0 credits), and a fallback action (watch_account). Complements annotations without contradiction.

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?

Every sentence adds critical information: purpose, safety/cost note, return fields, exclusions, and usage triggers. Front-loaded with the main action and scoped concisely for a list operation.

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 zero-parameter read-only tool, the description covers behavior, response contents, and exclusions comprehensively. An output schema exists to handle return structure, so nothing is left ambiguous.

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?

Zero parameters make the schema trivially complete (100% coverage). The description adds no parameter-level details because none are needed; baseline of 4 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?

States a specific verb (list), resource (creators tracked), and scope (authenticated user's), clearly distinguishing it from siblings like watch_account. The description also notes what it does NOT do (no snapshot payload) and references the sibling, making its purpose unambiguous.

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 provides trigger phrases and use cases ('what am I tracking', 'show my watches', 'list creators') and tells when to use the alternative tool (refresh baseline via watch_account). Covers both when and 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.

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

Annotations are minimal (readOnlyHint=false, no value for destructive or idempotent), and the description adds key behavioral constraints: a minimum of 3 reference samples and the fact that it returns a voice profile, reusable prompts, and the rewritten draft. It doesn't explain side effects or permissions, but the operation is a text transformation, so details are sufficient.

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 with no wandering. It front-loads the core purpose, then quickly lists requirements and output. Every clause adds information; 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?

For a moderately complex tool (two inputs, output schema present), the description covers the goal, the required inputs, the output structure, and the typical use-case. With an output schema provided, the description doesn't need to explain the return values, and it still manages to state what the result includes. Nothing critical is missing.

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%, and the description adds no extra meaning beyond what the schema provides (minItems on reference_samples, descriptions of draft and reference_samples). It touches on the requirement of 'at least 3 reference samples' but that's already encoded. 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's function: extract a creator's voice DNA and rewrite a draft in their style. It provides a specific verb+resource and so distinct outcome that it will be useful to an agent. While it doesn't explicitly name alternatives or siblings, its specificity (voice DNA, style matching) distinguishes it from casual rewriting tools.

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 'Use when the user wants to write in another creator's style or match a specific voice' gives clear direction. However, it doesn't mention when not to use it or point to an alternative (e.g., viral_remix or analyze_account), so it offers a clear context but no exclusions.

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 provide idempotentHint=true and destructiveHint=false, covering safety. The description adds behavioral context: 'adversarial verification' implies a rigorous analysis, and the list of outputs (attack vectors, calibration metrics) gives insight into the tool's processing. It also notes video URL auto-transcription, an external-access behavior, which is not in annotations. No contradiction with annotations.

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?

Two concise sentences with zero fluff. The first sentence states the action and outputs; the second gives usage condition and input options. The critical information is front-loaded, and every clause 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?

This is a complex tool with multiple output components, but the description enumerates all of them. It clarifies the input alternatives (script or URL) and the intended usage scenario. Given that an output schema exists, the description does not need to explain return values, and it covers the essential aspects an agent needs to invoke it correctly, distinguishing it from sibling tools.

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%, so the schema already documents both parameters. The description adds that the script should be a 'finished draft' for pre-publish verification, which is useful context, but it largely repeats the schema's note about accepting a video URL. No significant new meaning beyond the schema.

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 states a specific verb ('score') and a specific resource ('a draft script'), and lists unique outputs (virality score, recommendation, viral DNA breakdown, attack vectors, calibration metrics) that distinguish it from siblings like score_hook and find_viral_template. The phrase 'adversarial verification' further differentiates its approach.

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 gives a clear usage context: 'Use when the user has a finished draft and wants pre-publish verification.' It also specifies input format ('Pass either a script string or a video URL'). However, it does not explicitly mention when not to use it or alternatives, though siblings exist.

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 cover idempotency and non-destructiveness, so the description's job is lighter. It adds useful context about what the tool returns and that platform affects pattern matching, but it does not clarify whether any state changes occur or how much input content is processed. This is acceptable given the annotations, but still not rich.

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 compact and front-loaded, with a clear first sentence of what the tool does, followed by the result components and the explicit usage cases. Every sentence earns its place without redundant 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 simple parameter count, full schema coverage, available annotations, and presence of an output schema, the description is complete enough for an agent to invoke this tool correctly. It covers the target content, the decision, and the expected output categories.

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%, so the schema already documents `text`, `niche`, and `platform`. The description adds no per-parameter semantics beyond a minor mention that the platform affects pattern matching, which is already implied in the schema. 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 ('Score') and identifies the exact resource ('a TikTok, Reels, or Shorts hook') plus the method ('against proven viral patterns'). It clearly distinguishes this from sibling tools by focusing specifically on hooks and their improved variations, rather than broader virality prediction or account analysis.

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 has a draft hook to validate, wants to compare alternatives, or needs feedback before publishing.' It provides clear invocation context but does not name alternative tools or include explicit when-not-to-use guidance, keeping it one step below full differentiation.

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=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it mentions the 'degraded quality flag' for small regions, the client-side cutoff for window, and the platform-specific note that Instagram ignores region/date_posted params. This goes beyond annotations and helps the agent understand edge cases.

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, with the core purpose front-loaded and filters summarized in one sentence. It's efficient and doesn't waste words. A slight deduction because it could be slightly more structured (e.g., bullet points for filters), but it's still well-organized and readable.

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 (7 params, 2 enums, platform-specific behavior), the description covers the key points: what it returns, when to use it, and the main edge cases (region coverage, platform differences). The output schema exists, so return values are covered. It doesn't mention pagination or rate limits, but those are minor for a search tool. A 4 is fair.

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%, so the schema already documents all parameters well. The description adds value by summarizing the optional filters (niche, minimum views, recency window, region) and by noting the 'degraded quality flag' for regions, which is not in the schema. It doesn't repeat schema details but adds a layer of context, so a 4 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 states a specific verb ('Search'), a resource ('short-form videos'), and the platforms ('TikTok or Instagram'). It clearly distinguishes from siblings like 'find_viral_template' or 'trend_pulse' by focusing on keyword search for videos. The scope and output are explicit.

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 find videos about a topic or keyword,' which provides clear context. It doesn't explicitly name alternatives or when-not-to-use, but the sibling list and the specific phrasing make the usage context clear enough. A small deduction for not naming alternatives explicitly.

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 providing the safety profile (idempotent, non-destructive, open-world), the description adds value by disclosing what the tool returns — growth signals, data sources, saturated patterns to avoid — and the deadline_hours param goes deep on derived fields (trend_status, deadline_verdict) and their semantics. No annotation contradiction: 'Research... Returns' is consistent with idempotentHint (same call yields stable trends data within a window) and openWorldHint (trending data shifts with the world). It stops short of full transparency — no mention of rate limits, pagination, latency of data freshness — but for a query-style tool with an output schema, the coverage is solid.

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 well-architected: first sentence nails the core operation, second describes the return shape, third gives explicit invocation triggers, and the fourth scopes it. Every sentence earns its place, and the most important information is front-loaded. The main deduction is that the schema's deadline_hours description carries a verbose, almost narrative 'magic-genie ritual' framing that may confuse an agent; while not part of the main description text, it inflates the tool definition's overall signal-to-noise ratio.

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 tool with 3 optional parameters, an output schema, and no nested objects, the definition is complete — it explains the domain (short-form trend research), what's returned, when to call it, and the parameter semantics are fully self-documenting. The description meaningfully complements the schema by answering the 'how would an agent use this in practice' question. Gaps are minor: no mention of data-source-specific latency, and the niches/region feature-count is slightly inaccurate (18 vs 17 listed).

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%, so the rubric's baseline of 3 applies — and the schema carries the full weight here. The description does echo the two key knobs ('Supports 17 niches and optional region filtering'), but adds no semantic layer beyond what the parameter descriptions already state (e.g., region maps to Google Trends geo + YouTube regionCode; Reddit ignores region). It also perpetuates the '17 niches' inaccuracy instead of resolving it. The description is a competent summary, not an addition.

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-scope statement: 'Research what is currently gaining traction in short-form content for a specific niche' — clear and unambiguous. It then reinforces the purpose with concrete return types (formats, hooks, styles, topics) and saturated patterns to avoid. It loses the fifth point because it never names any sibling (e.g., find_viral_template, predict_virality) to explicitly disambiguate where its scope ends, so the differentiation is implied rather than explicit. One small blemish: it claims '17 niches' while the enum defines 18.

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 gives explicit trigger conditions — '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' — which is exactly the right kind of when-to-use signal. The deadline_hours parameter adds behavioral guidance ('use this on every brief-just-landed call'), showing when to enrich the default call. It gets dinged because it never says when NOT to use it or names an alternative tool for adjacent intents like predicting performance (predict_virality) or finding templates (find_viral_template).

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 discloses meaningful behavioral details beyond annotations: it returns a structured script package, and it states that passing target_product + verified_product_facts prevents the generator from fabricating product details. Annotations already cover read-only/destructive/idempotent hints, and the description does not contradict them.

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 with no filler: purpose, output, usage trigger, and critical product-grounding rule. It is 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?

Given the rich input schema, output schema, and annotations, the description covers the essential invocation decisions: what the tool does, what inputs are acceptable, and the mandatory product-facts pairing for grounded promotion. No critical information for selecting or calling the tool is missing.

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%, so the schema already documents all eight parameters thoroughly. The description adds 'ALWAYS pass target_product + verified_product_facts' and 'Pass either a video URL or a transcript directly,' but these largely restate or emphasize schema semantics rather than introducing new parameter meaning.

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 states a specific verb and resource: 'Take a viral video and produce a fresh script that mirrors its structure and energy pattern for a new topic.' It also enumerates concrete outputs (formula, scene-by-scene script, voiceover, visuals, camera directions, text overlays), making the tool's function unmistakable and distinct from siblings like find_viral_template.

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 gives an explicit trigger condition: 'Use when the user finds a video they want to replicate the structure of.' It also provides input-mode guidance (URL vs transcript) and a product-promotion rule. It does not explicitly state when not to use it or name alternative tools, so it falls 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?

Beyond the idempotentHint and openWorldHint annotations, the description elaborates on side effects: it creates a watch, is idempotent (returns existing watch on repeat), costs 5 credits only on the first call, and reuses the 'analyze' permission without new OAuth scope. This provides rich behavioral detail not captured in annotations alone.

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 informative but slightly redundant—idempotency and credit costs are mentioned in overlapping ways (e.g., 'returns the existing watch with credits_charged=0' and 'Costs 5 credits ONLY on the first call'). It's not overly long, but could be tightened without losing meaning.

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 covers the tool's purpose, trigger phrases, side effects (credits, idempotency, permission reuse), and the parameters are fully explained in the schema. It does not need to describe the output schema per the guidelines. Overall, an agent has sufficient context to decide when and how to call this tool.

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% (both handle and platform have descriptions), so the baseline is 3. The tool description does not add extra nuance about parameter formats or constraints beyond what the schema already provides, so no bonus.

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 action ('Start tracking a creator') and the specific resource (a durable CreatorWatch and baseline snapshot), distinguishing it from siblings like analyze_account or get_changes. It also provides explicit trigger phrases ('track', 'watch', 'follow'), making the purpose unmistakable.

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 says track, watch, follow...' which gives clear, actionable guidance. It also implies the tool is for setting up monitoring for future change detection, which contrasts with tools like get_changes (retrieving changes) or list_watches (listing existing watches).

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