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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: unreported fields come back as 'not present' rather than estimated, a freshness warning fires when evidence ages differ by more than two days, and unowned ids surface in missing[]. These are non-obvious traits an agent could not infer from structure.

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 the core action and scope, then a tight sequence of constraints; essentially every sentence carries distinct information. It runs long enough that a couple of clauses (e.g., the enumerated facet list) could be trimmed, keeping it just short of a 5.

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 no prose. Against that, the description covers input bounds, ownership failure handling, evidence-freshness caveats, and the sequencing context, leaving nothing an agent needs to call 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?

With 100% schema coverage the schema already documents saved_ids, its 2-4 bounds, and the id pattern, so baseline is 3. The description adds meaning beyond the schema by clarifying what happens to ids the user does not own (they land in missing[]), covering the failure case the schema cannot express.

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 (compare), resource (2-4 saved analyze_product results), and scope (side by side using only stored evidence) with the exact facets compared. An agent can distinguish it from analyze_product and list_saved_research 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?

Explicitly sequences the tool ('Use after list_saved_research') and gives the triggering user intent ('which of their saved products to pursue'). It also rules out fresh analysis, but never names the sibling an agent should reach for instead when the user wants new analysis, so it stops short of full when-not/alternative coverage.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered; the description still adds two things the annotations cannot: zero credit cost and the ownership scoping rule ('only the authenticated user's own results resolve; any other id is not found'). The 'Read-only' clause is redundant with annotations but the cost and auth facts are substantive.

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 action and return contents, then cost/safety, then the routing condition. Every sentence carries distinct information; nothing is padding.

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 single-parameter retrieval tool with an output schema and full annotation coverage, the description supplies the remaining unknowns: what comes back, what it costs, who can read what, and when to prefer it. An agent can call it correctly and interpret the failure case.

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 0% – the saved_id pattern constraint is undocumented in the schema. The description compensates by explaining the id's semantics: it must be one of the caller's own saved results and foreign ids resolve as not found, which is the key behavior an agent needs to interpret a lookup failure.

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 (Retrieve) plus resource (one saved result in full) with a parenthetical enumerating the payload contents. The word 'one' and the scope 'in full' cleanly separate it from list_saved_research and save_research without requiring the 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 when-to-use trigger: 'when the user wants to reuse, re-read or build on something they saved earlier instead of paying to run the tool again.' That contrast with re-running a paid tool is a genuine alternative-routing signal, though no sibling (e.g. list_saved_research) is named for the discovery case.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: zero credit cost, cursor-based paging, and the fact that results are summaries rather than full research payloads. It does not state a default/max page size, which is the only notable gap.

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 the core purpose, then filtering/paging, then return shape, then usage triggers – a logical order with no filler sentences. It is dense and slightly long, but each clause carries distinct 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?

For a 6-param list tool with an output schema present, the description covers filtering, sorting, paging, return content, cost, and routing to the detail sibling. An agent has everything needed to call 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 coverage is only 50%, so the description does needed work: it names the kind filter, title search, the sort enum (newest|oldest|title), the archived inclusion (and that active is default), and the cursor for paging. Only 'limit' is left undocumented outside 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+resource ('List the authenticated user's saved HookLayer research') plus the default ordering, and explicitly distinguishes itself from the sibling get_saved_research ('Returns summaries ... not the full result; call get_saved_research for one'). An agent can route between the two without opening either 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 when-to-use block with three concrete user phrasings ('what have I saved', 'show my saved products', 'find the analysis I saved for @handle') and a named alternative (get_saved_research) for the single-item case. Nothing 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?

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?

Far exceeds the annotations (which only say readOnly=false, openWorld=true, idempotent=false, destructive=false). It discloses that status comes from a qualification gate rather than the score, defines what each status requires, explains the NO_VERIFIED_OPPORTUNITIES outcome and how to report it, warns that Amazon competition is never measured, notes provider_reported.* nulls mean unknown not zero, and states there is no revenue/GMV field. 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?

Purpose and routing are front-loaded, and nearly every sentence carries a non-obvious rule (gate semantics, null-means-unknown, no-revenue caveat). It is a dense single block rather than a structured list, which hurts scannability for a 350-word description, but almost nothing is 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 21-parameter, zero-required, complex ranking tool with an output schema present, the description supplies everything an agent needs to invoke and interpret it: entry conditions, filter semantics, gate-based status rules, empty-result handling, and the no-revenue/no-Amazon caveats. Return-value explanation is appropriately delegated to 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 description coverage is 100% and the schema already documents every one of the 21 parameters in depth (sort modes, strict-filter drop behavior, cold-start refusal). The description adds interpretation rules about scores/statuses but little per-parameter meaning beyond what the schema 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+domain: 'Find and rank current TikTok Shop / social-commerce product opportunities using evidence rather than opinion,' and immediately distinguishes itself from analyze_product, search_videos, and analyze_account by name. An agent can tell what this tool does and what it is not without opening the 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?

Gives concrete triggering questions ('what skincare products are breaking out in the US under $40'), an explicit sibling hand-off rule ('product_scout ranks a field of candidates, analyze_product interrogates one'), negative guidance ('Not for generic video search... creator analysis... guaranteed-sales claims'), plus cost (5 credits) and the shop_intelligence entitlement prerequisite.

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?

Goes well beyond the annotations: states zero credit cost, that the tool never re-runs research, that billing and chain fields are dropped server-side, and that a stable request_id deduplicates retried saves. It also discloses the return shape (saved id and dashboard link). The idempotentHint annotation is reinforced with the actual mechanism rather than repeated.

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 cost model are front-loaded in the first two sentences, and the routing alternatives are appended at the end where they belong. The single dense paragraph is efficient, though it packs several distinct concerns (cost, offering behavior, params, return, read-back) without visual breaks.

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 9 params, nested objects, an output schema and a high-risk mutation profile, the description covers credits, idempotency, server-side field handling, return values and alternatives. It omits edge cases such as size limits beyond the 64 KB schema note or behavior under an exhausted credit balance, but nothing essential for correct invocation 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 coverage is 100% so the baseline is 3, but the description adds real meaning: what to pass as result (the tool's structured output, with billing/chain fields stripped), the need for a matching kind, a short title, and a stable request_id for retry dedup. It does not restate the enum-to-tool mapping already in the schema, but the added behavioral framing of the key params justifies an above-baseline score.

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 ('Save a HookLayer result ... so it appears under Saved Research') and immediately scopes it to results the user already received, distinguishing it from the research-producing siblings like analyze_product or score_hook. An agent can tell what this does and what it does not do (re-run research) without opening a 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?

Gives explicit trigger conditions ('call this only when the user says yes or asks to save, keep or bookmark a result') plus an interaction convention (offer once in one line after a result). It also routes reads to list_saved_research / get_saved_research and 2-4 comparisons to compare_saved_products, naming concrete alternatives.

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?

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: product_id linkage semantics and the region-verified vs unknown distinction, which are not in the parameter descriptions. It stops short of value-format guidance (e.g., how to phrase niche or region).

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

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

States a specific verb (search) and resource (short-form videos) with scope (keyword, TikTok/Instagram) and output shape (up to 20 ranked by engagement). No sibling tool performs video keyword search, so it is cleanly differentiated from trend_pulse, find_viral_template, etc.

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

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

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

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

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.