PrePublish - YouTube script QA

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

Annotations only carry readOnlyHint=false and openWorldHint=true; the description adds genuine value beyond these. The 'text-only check of an unrecorded script' and 'maps relative attention risk... does not measure or predict published retention, cannot account for delivery, editing, thumbnail, topic or distribution' disclosures clarify what the tool will and won't report. The one gap: the schema's email/quota mechanics (free daily check, then email required) are not explained in the description, leaving an operational behavior undocumented. 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?

Lengthy but densely informative — every clause earns its place. The first sentence front-loads purpose with specifics, the second gives usage guidance, and the closing sentences cover scope disclaimers. It could be slightly tighter (the 'Could not account for...' list repeats the thrust of 'does not measure retention'), but 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?

With no output schema, the description carries the burden of describing return values, and it does: attention pull per sentence, curiosity gap, payoff distance, top issues, and rewritten alternatives. Combined with explicit scope limitations and usage routing, an agent has everything needed to invoke it correctly. Only the email/quota operation is externalized, and the schema handles that.

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 and the schema already documents all three parameters fully (email's conditionality, niche's optionality, hook_text's format and length). The description reinforces hook_text via 'hook or opening paragraph' but adds no parameter semantics beyond what the schema supplies. It correctly meets the baseline without exceeding it.

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 (score), resource (opening lines of a YouTube script), and enumerates the concrete outputs: per-sentence attention pull, curiosity gap, payoff distance, top issues, and rewritten alternatives. It further carves out its exact scope relative to audit_script, so an agent can distinguish them without inspecting other schemas.

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 when-to-use conditions ('shares only a hook or opening paragraph', 'wants a fast second opinion'), names the alternative tool audit_script directly, and frames the tradeoff ('Cheaper and narrower'). The scope exclusions (doesn't measure retention, can't see delivery/editing/thumbnail) also steer an agent away from misapplying 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?

Adds meaningful context beyond the annotations: the email-gated free result, the text-only scope of a pre-record check, and a clear boundary on what it does NOT measure (retention, delivery, thumbnail, topic). The readOnlyHint=false is consistent with 'audit' being a computation. Minor deduction because it doesn't state the return shape of the attention-risk map beyond narrative prose.

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-loads the action and return, then triggers, then exclusions, then the email caveat, then scope limits. Every sentence earns its place with no redundancy or restatement of the name.

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?

Complete for a 6-param no-output-schema audit tool: it covers purpose, return signals, prerequisites (email), and failure-adjacent limits. The only shortfall is absence of any guidance on the audience/category/duration optional params, though the description's restraint is deliberate.

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 baseline is 3. The description supplements with behavioral rules — 'paste it verbatim', 'ask the user for an address rather than guessing one' — that add instruction beyond the schema, but does not deepen per-parameter meaning beyond what the schema already provides.

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 (run full audit) and resource (YouTube script the user has already written), and enumerates what comes back (hook/structure/pacing scores, attention-risk map, rewrites). It explicitly distinguishes itself from siblings: 'Do not use it to generate a script, to review a published video' sets it apart from audit_hook and check_authenticity.

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 positive trigger ('finished or near-finished draft... what is weak before they record') plus three explicit exclusions (generate, review published video, check grammar). It also instructs the agent to collect an email rather than guess one, which is a concrete pre-call behavior.

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 clearly discloses what the tool returns (score, risk level, signals, remediation) and its limits (text-level signals only, not a monetisation decision). It does not mention side effects or external calls, but the verb 'check' plus readOnlyHint=false is not contradicted; a small gap remains about whether any state changes occur.

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 but information-dense, opening with the purpose and then listing output and limits. No redundancy; the only minor cost is having outputs stated in two places, but this is not waste.

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 no output schema, the description supplies the full return contract (score, risk level, signals, remediation). It also gives a usage trigger and a boundary. It lacks edge-case/error behavior, but that is not essential for selection and invocation.

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

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

Schema coverage is 100%, and the schema already describes both parameters well, including the 'do not rewrite or summarise' instruction in script_text. The description adds no parameter-specific guidance 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 action ('Check a script against YouTube's inauthentic-content expectations') with a clear object and scope. It enumerates exactly what is evaluated (mass-produced/templated/repetitive text) and what is returned (score, risk level, signals with quotes, remediation), making it easy to select.

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?

Names concrete trigger conditions: 'when the user worries about reused content, AI-sounding scripts, or a formulaic channel.' It gives an exclusion ('not a monetisation decision') but does not name an alternative sibling tool explicitly, so an agent must infer which sibling covers monetization.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value: it is text-only, costs nothing, works on an unrecorded script, and explicitly scopes what it does NOT measure (retention, delivery, editing, thumbnail, topic, distribution). It stops short of describing return shape or polling/expiry behavior, keeping it below 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?

Front-loads the core action and the id source, then layers usage and scope. Slightly long with several scope-limiting clauses, but each sentence carries distinct routing or boundary information rather than redundancy.

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-param read tool with annotations covering safety and no output schema, the description supplies the needed usage context and the important negative scope. It could note whether results are transient or how to interpret the attention-risk output, a small remaining gap.

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

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

Schema coverage is 100%, and the schema already documents analysis_id including its origin from audit_script. The description reinforces the provenance but adds no syntax, format, or constraint beyond the schema, 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 and resource (fetch audit state by analysis_id) and explicitly anchors it to the sibling audit_script that produces the id. An agent can distinguish this from audit_script/audit_hook without opening schemas.

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 when-to-use conditions (previous audit still running, or user references an earlier audit) and clarifies it performs no new analysis, which routes the agent away from re-running audit_script. 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?

The description adds useful context beyond the annotations: the free result may return locked quotes, quoted passages and rewrites belong to the paid audit, and the tool is explicitly not a monetisation guarantee. Nothing contradicts the annotations, though side effects are not elaborated.

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 dense but front-loaded: the first sentence states purpose and outputs, the second gives usage selection, and the rest add necessary caveats about paid/free behaviour and scope. It could slightly tighten the policy-page citation clause, but it is not padded.

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?

Even without an output schema, the description covers the main result elements, the intended use case, the paid/free boundary, and the tool's limitations. It does not spell out an exact response structure, but an agent has enough signal to decide when to call it.

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 schema already documents both title and script, including the 200-character minimum. The description adds only minor extra framing about checking before recording and does not need to compensate for missing schema details.

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 action ('Check a script before recording') and lists concrete outputs: category families implicated, consequence family, verdict, and flag counts. It also differentiates from the paid audit siblings by describing this as the preflight/free version with locked quotes.

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

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

The description gives an explicit selection trigger: choose this when the user discusses sensitive subject matter and asks whether monetisation is safe. It references a paid audit alternative for quoted passages, but it does not explicitly name a sibling tool or provide a clear when-not-to-use condition.

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=true, openWorldHint=false), and the description adds substantial context beyond them: the data provenance (measurement of 349 videos), the rate spread (160/181/201 wpm), and the scope caveat that pauses and B-roll are excluded so real edits run longer. That is exactly the kind of expectation-setting an agent needs before quoting a number to a user.

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 operation, then usage triggers, then the caveat — a sensible order. The percentile figures are slightly dense but they justify the rate model rather than padding, so every sentence earns its place.

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

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

With no output schema, the description does the work of saying what comes back (a runtime range, or a word budget). Combined with the 100%-covered parameter schema, an agent has enough to invoke correctly; only minor detail like exact rounding or whether multiple inputs may be combined is left implicit.

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 goes further by explaining the three distinct input modes and what each produces (word count → range, pasted script → range, target minutes → word budget). It doesn't restate the mutual-exclusivity rule, which the schema already handles.

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 bidirectional operation: word count/script → runtime range, and target runtime → word budget. An agent can tell exactly what it does without opening the schema, and the purpose is distinct from the audit-oriented siblings.

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 phrasings ("how long will this script run", "how many words for a ten-minute video") and an explicit exclusion (pauses, B-roll, demonstrations), which tells the agent when the answer will understate a finished edit. No sibling alternative is named, but none of the siblings is a substitute for this arithmetic tool.

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