hooklayer

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: YouTube videos with captions disabled or geoblocked resolve to transcript: null, Instagram lacks lifetime totalLikes so it defaults to 0, and an empty filter match returns a warning with no credits charged. It does not explain the general credit cost implied by readOnlyHint=false, so it falls short of a 5.

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?

Dense but well front-loaded: purpose and return payload come first, then usage trigger, then platform support. Platform capabilities are stated twice (opening sentence and closing sentence), which is mild redundancy, but every sentence carries substantive 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?

With an output schema present, the description needn't enumerate return values, and it covers usage, platform scope, and platform-specific limitations, so an agent has enough to call it correctly. Minor gaps remain around credit cost and when to choose this over watch_account, but nothing essential 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 handle, since, window, platform, and recent_only in detail, including the since/window mutual exclusion. The description only restates that input is a handle or channel ID and describes per-platform behavior rather than adding parameter-level meaning, so the 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?

States a specific verb (analyze) and resource (creator account by handle or channel ID) and enumerates the concrete outputs (viral DNA scores, format fingerprint, headline_insight). It clearly separates itself from siblings like watch_account or predict_virality by scoping to one-shot account analysis across three named platforms.

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 says 'Use when the user asks to analyze a creator, account, channel, or competitor,' which gives the agent a clear trigger condition. However, it never names an alternative or exclusion — for example, when to prefer watch_account for ongoing monitoring versus this one-shot analysis — so routing among siblings is left to inference.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description adds substantial context beyond them: 10-credit cost, entitlement requirement, no GMV/revenue output, sold counts never multiplied by price, evidence provenance being distinguishable, and thin evidence reported as thin rather than fabricated. This is unusually rich behavioral disclosure.

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?

Front-loaded correctly — purpose, input, and method come before the output enumeration. The 'You get:' list is long and partly duplicates the output schema, but each item is decision-relevant for a costly tool rather than 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 complex, credit-costing, entitlement-gated analysis tool, the description covers inputs, cost, gating, output shape, evidence-handling caveats, and sibling sequencing. Nothing needed to invoke it correctly is missing, even though the output enumeration is arguably redundant given the output 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 coverage is 100%, so parameters are already documented. The description still adds selection rationale for include_competitors ('the differentiated part of this report; set false only when... the credit cost is the same either way') and orients market/product_id to their source, going modestly 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?

States a specific verb and resource ('Deeply validate ONE TikTok Shop product') and immediately positions itself against product_scout by framing the goal as 'before committing money or content to it.' An agent can distinguish it from all siblings, especially product_scout, without opening any schema.

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 sequencing: 'Use product_scout first to find candidates, then this to decide between them.' It also names the precondition ('Requires the shop_intelligence entitlement') and the cost (10 credits), which are the practical gates an agent needs before calling.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive), and the description adds substantial extra context: a 7-credit cost with a stated discount rationale, the upstream chain it wraps, and importantly the non-obvious caveat that when quality.level is not "full" or verdict is NEEDS_MORE_DATA/NO_GO the output is not shippable. It stops short of describing auth/prerequisites, so it is strong but not exhaustive.

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 outcome is front-loaded in the first clause ("Turn a brand brief ... into a one-page creative blueprint") and every subsequent sentence adds distinct information (trigger, chain, cost, return shape, caveat). It is dense and the first sentence runs long, but there is little 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 7-parameter, high-complexity orchestration tool, the description covers trigger conditions, cost, upstream dependencies, the shape of the result, and the interpretation caveat for degraded verdicts. An output schema exists, yet the description still summarizes return fields in a way that helps an agent decide whether the result is usable.

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%, including the enum mappings, region threading, platform behavior, creator_handle voice matching, and how deadline_hours affects trend scoring — so the schema carries the parameter burden. The description adds only high-level phrasing ("trend-velocity check", "creator context") that does not extend beyond the field-level docs, which is the expected baseline when coverage is complete.

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 transformation (brand brief → one-page creative blueprint) and enumerates exactly what the artifact contains (hook, template, hashtag combo, trend-velocity check, shoot instructions). It also distinguishes itself from siblings by naming the chain it bundles (find_viral_template + trend_pulse + score_hook + predict_virality) and explaining they are exposed as one 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?

Gives an explicit triggering scenario ("product arrived, need content in 48 hours") and the persona/condition (manager needs a defensible direction with no research time). It also implicitly routes agents away from manually stitching the four upstream sibling tools.

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 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.

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.

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.

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.

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.

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.

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?

With annotations limited to readOnly/openWorld/idempotent/destructive hints, the description carries the real behavioral load: deterministic 9-component engine with no model output, cost of 5 credits, shop_intelligence entitlement requirement, null-means-unknown semantics for provider_reported.*, absence of any revenue/GMV field, and the instruction never to present the score 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?

Front-loaded with purpose, then example questions, return semantics, sibling routing, and cost. Dense and information-rich, but several clauses (revenue/GMV caveats, provider_reported explanation) are somewhat repetitive relative to their operational value.

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 21-parameter open-world ranking tool with an output schema, the description supplies everything an agent needs: what it ranks, the component/status/confidence model, how to interpret why_now/risks, and how to route to analyze_product. Nothing material is missing despite the output schema already covering return shape.

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 21 parameters in detail (including strict-filter and cold-start behaviors). The description adds engine-level context but no additional parameter syntax or format meaning beyond what the schema provides, so the baseline of 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?

States a specific verb+resource ('Find and rank current TikTok Shop / social-commerce product opportunities') with a clear differentiator ('using evidence rather than opinion'). It explicitly distinguishes itself from siblings by naming analyze_product, search_videos, and analyze_account and describing what each does instead.

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?

Provides concrete example questions that select this tool, gives the explicit handoff rule ('once you have a shortlist, call analyze_product'), and names when NOT to use it (generic video search, creator analysis, guaranteed-sales claims). Alternatives and conditions are fully spelled out.

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?

Annotations supply openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the behavioral bar is lowered; the description usefully adds that results include growth signals, data sources, and saturated patterns to avoid. However it does not reconcile the tension between the read-flavored 'Research/Returns' framing and readOnlyHint=false, nor mention latency or external-source behavior for an open-world research call.

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 purpose and then usage, with no filler and a clean reading order. It is efficiently sized for the complexity, though the niche/region sentence is largely redundant with the schema.

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?

An output schema exists, so return values need not be restated, and the description covers purpose, triggers, and scoping (niche, region). The one gap is that the significant deadline_hours parameter and its deadline_verdict behavior are neither referenced nor alluded to in the description.

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 enum niche list and region semantics are already fully documented in the schema; baseline 3 applies. The description only echoes '18 canonical niches' and 'optional region filtering' and never surfaces deadline_hours, but adds nothing beyond the 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?

The description opens with a specific verb+resource ('Research what is currently gaining traction in short-form content for a specific niche') and enumerates the returned artifacts (formats, hooks, styles, topics). It is clearly distinguishable in intent from analyze_* and score_hook, but it never names a sibling or explicit boundary to disambiguate from find_viral_template/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 'Use when...' clause gives concrete trigger conditions: 'what to post about', 'what's trending in a niche', or validating a content idea against trends. That is clear when-to-use context, but there are no when-not conditions and no named alternative tool, so routing is left partly to inference.

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 only cover safety (not read-only, open-world, non-idempotent, non-destructive). The description goes well beyond that: it discloses that the generator will not invent product names, prices, timelines, features, or customer stories, and that omitting verified_product_facts causes degraded output. That is substantive behavioral disclosure an agent cannot infer from the annotation block.

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?

Purpose and output are front-loaded in the first two sentences, then the trigger condition, then the parameter rules. Five sentences, each carrying distinct information with no 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?

With an output schema present the description need not spell out returns, yet it still previews them briefly. Together with annotations carrying the safety profile and 100% schema coverage, an agent has everything needed to select and call this 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?

Schema description coverage is 100%, so the baseline is 3. The description still adds value by stating the either/or input contract in prose and by elevating the target_product + verified_product_facts pairing to an ALWAYS rule, which reinforces the grounding semantics beyond the schema's per-field wording.

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+resource ('take a viral video and produce a fresh script that mirrors its structure and energy pattern for a new topic') and enumerates the deliverables, so the agent knows exactly what comes out. It does not name or differentiate from close siblings like find_viral_template or brief_to_blueprint, which an agent might plausibly confuse this with.

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?

Gives a clear triggering context ('when the user finds a video they want to replicate the structure of') and an explicit input-mode rule (URL or transcript). It also mandates target_product + verified_product_facts for product promotion. No when-not guidance or named alternatives, 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 idempotentHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the exact cost model (0 credits on cache/watch reuse, 5 credits on a fresh baseline), the credits_charged=0 return signal, and reuse of the existing 'analyze' OAuth permission with no re-consent. This is richly disclosed behavioral detail an agent needs.

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?

Six sentences, all earning their place, with the core purpose front-loaded followed by usage triggers, idempotency, cost, and permissions. Slightly dense, but no wasted filler and information is ordered by importance.

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 an output schema, the description need not explain return values; it covers everything else an agent needs — purpose, triggers, idempotency semantics, cost, and auth implications. Nothing material 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 both parameters (handle, platform) are fully documented in the schema, including format examples and enum values. The description references 'watch @same' but adds no syntax or format detail beyond what the schema already provides, so the 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?

States a specific verb+resource ('Start tracking a creator') and immediately names the artifacts it creates (durable CreatorWatch + baseline CreatorSnapshot). Distinguishes itself from siblings like analyze_account, list_watches, and get_changes by describing what it produces rather than merely restating its name.

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?

Gives explicit trigger phrases ('track', 'watch', 'follow', 'keep an eye on'), states idempotency conditions, and identifies the relationship to analyze_account (which it invokes for a fresh baseline). The agent knows both when to call it and what it will cost.

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