Persuasion Taxonomy

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds substantial context beyond them: it names the nine reader questions the check reports on, the swap test, the cutoff preview, outright failure flags, and evidence pooled from thousands of real tests. It also proactively sets an expectation ("You won't get a score out of ten") that prevents misuse of the result.

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 and output content, and every sentence does work, including the expectation-setting line about no score out of ten. It is on the long side and the middle sequencing is a touch dense, but there is 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 no output schema, the description fully carries the burden of describing returns: what each line is judged on, which reader questions it answers, whether a competitor could send it unchanged, the cutoff view, failure flags, evidence, and a recommended two-variant test. Nothing needed to call it correctly 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 80%, so the schema carries most of the burden, but the description adds real meaning: "Before you call it, list the reader questions each line answers and quote the exact words doing the work" tells the agent the required 'answers' payload must be authored by the caller. The swap-test note also clarifies why the brief matters.

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 (check, compare) and a precisely scoped resource: headlines, email subject lines, ad openings, video hooks, social post openings/first lines. The enumeration of line types plus the comparison framing makes it easy to separate from the broader diagnose_marketing_copy sibling 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?

Gives explicit when-to-use triggers: "whenever you write headlines, hooks or subject lines, whenever you have to choose between them, and whenever someone asks 'which one is best?'". It does not name a when-not condition or point at the closest alternative (diagnose_marketing_copy), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses what classes of problems are reported (vague superlatives, promises without proof, results without mechanism, generic CTAs) and that output includes remediation suggestions ('tells you how to fix each one').

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?

Five sentences, front-loaded with the core purpose before the examples and the sibling hand-off. Each sentence carries distinct information (what it catches, that it proposes fixes, when to use, when to use something else), though the detection list is slightly repetitive.

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, read-only checker with no output schema, the description covers purpose, detection scope, remediation behavior and fallback routing. The only gap is concrete input formatting for the claims array, which is a minor omission given the schema fields.

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 description references the input conceptually ('claims like ...', 'any button text'), which maps loosely to the claims text and type fields, but it gives no format or batching guidance. Schema description coverage is reported as 0%, so the description does not fully compensate for the parameter documentation gap, though the nested schema itself is self-describing.

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+resource: it checks marketing claims and CTAs and says exactly what it detects (vague superlatives, unproven promises, generic buttons). It also distinguishes itself from the sibling check_headlines, which 'does the full job' for headlines, so an agent can route correctly 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 with concrete examples ('results in days', 'trusted by thousands', '#1 tool', any button text) plus an explicit boundary: for headlines, use check_headlines instead. Nothing about routing 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 already establish that this is a safe, idempotent, non-open-world read, so the barrier is low, and the description adds real behavioral value: it discloses that the caller must pre-label each line into the moves array, and what the response contains (nine-question coverage, biggest gap, order, agreement, craft/machine-written markers). It stops short of covering limits like the 80-move cap or behavior on unparseable input.

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 the pre-call workflow before the description of outputs, and every clause carries information. It is a dense, long run-on paragraph, so scanning is harder than it needs to be, but there is little outright 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 nine-parameter tool with nested objects and no output schema, the description covers the purpose, the required pre-work and the shape of the result well enough to call it correctly. The remaining gap is that return structure is described narratively rather than concretely, and sibling boundaries are 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 description coverage is 100%, so the schema already documents all nine parameters including enums, defaults and nesting; the baseline of 3 applies. The description reinforces the labeling workflow for moves but adds no syntax, format or constraint detail beyond what the schema 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 set (review, critique, roast) against a specific resource (any piece of marketing copy) and enumerates the formats it covers. It does not explicitly name sibling tools it overlaps with, such as check_headlines, check_marketing_claims, or find_persuasion_techniques, even though the description claims to also do opening-line checks and suggest techniques.

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 trigger conditions and even quoted user phrasings ('is this good?', 'roast this', 'what's wrong with this copy?') plus the recommended timing before showing a draft. It never states when NOT to use it or which sibling tool to pick for a narrower job.

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 annotations already mark this as read-only, idempotent, and closed-world, so the bar for behavioral disclosure is lower. The description still adds rich value by explaining what comes back: likely unanswered reader questions, what to check in copy first, problems copy cannot fix, techniques to try, and a confirming test. There is no contradiction with the annotations.

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

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

The core purpose is front-loaded, but the description is long and enumerates symptom cases that largely duplicate the detailed enum descriptions in the schema. It is readable but not tight; several clauses could be removed without losing meaning.

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

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

The description covers the diagnostic purpose, when to use the tool, and the shape of the returned analysis, which is important because there is no output schema. It is nearly complete for invocation. The main gap is lack of routing guidance against the sibling diagnose_marketing_copy.

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 input schema already fully documents the five parameters and their enums. The description restates symptom examples in narrative form but adds no syntax or constraints beyond what the schema provides. The baseline of 3 is appropriate when structured fields carry the parameter semantics.

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 diagnostic purpose: working out why an ad, landing page, email or funnel isn't converting. It scopes the tool well against planning or checking siblings. However, it does not differentiate from the closely named sibling diagnose_marketing_copy, so an agent still has to infer which diagnostic tool to choose.

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

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

It gives clear trigger conditions: use whenever someone says marketing 'isn't working', 'isn't converting', 'isn't selling', or asks why results dropped. This is strong when-to-use guidance. It lacks any when-not guidance or explicit alternative sibling, which keeps it below 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 readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact contents of each result (name and ID, one-line definition, real example, category frequency if a category is named, link), which matters because there is no output schema.

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

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

Front-loaded with the corpus definition, then usage scenarios, in a logical order. Slightly loose — 'It finds the techniques that do it.' is filler and the long run-on sentence mixes four separate example queries that partly duplicate the schema's own query example.

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 usefully specifies what comes back, and it covers corpus size, organization and triggering scenarios. Minor gaps: nothing about result ordering/relevance or how the default limit of 8 affects behavior, though the schema covers those parameters.

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 already 80%, so the baseline is 3. The description earns above baseline by explaining intent-level semantics: the query is phrased as 'describe what you want the copy to do' with multiple worked examples, and it clarifies that any category value other than the listed ones still works but suppresses the comparison signal.

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 — search the Persuasion Taxonomy of 766 named techniques organized by nine reader questions — and makes the scope concrete enough to separate it from the singular get_persuasion_technique sibling. An agent can tell what it returns and roughly how the corpus is structured 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 explicit triggering contexts: 'reach for it when a draft relies on the obvious move and you want a less expected one, or when someone asks for tactics, angles, hooks or ideas.' Strong when-to-use signal, but it never names an alternative tool or states when not to use it (e.g. the single-technique lookup or the diagnostic siblings).

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 and closed-world, so the safety profile is covered. The description goes further by enumerating what comes back (definition, why it works, when it backfires, ad examples, related/opposite techniques, citable link), which is real behavioral value beyond the structured fields.

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 what and the identifier forms, then a single usage sentence with no filler. The return-value enumeration is a long clause but it carries information since there is no output 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 no output schema, the description correctly compensates by describing the payload, and the annotation set covers safety. The one gap is silence on the optional category parameter and its comparison behavior, which the schema documents on its own.

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 both parameters are already documented and the category comparison behavior lives in the schema. The description adds only the concrete PT-ID format example ('PT-PRV-10000'), and notably never mentions the category parameter at all, so it stays at the baseline.

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 (look up) and resource (one persuasion technique) plus the accepted identifier forms (PT-ID, slug, exact name). It reads as a single-record retrieval tool, clearly separable from the sibling find_persuasion_techniques, which is exploratory search.

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 triggers: use before applying or recommending a technique, and whenever someone asks what a tactic is called or how it works. It sets context well but never names the discovery alternative (find_persuasion_techniques) or states when this lookup is the wrong choice.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed world, so the safety profile is covered; the description adds the useful behavioral fact that this is a deterministic advisory calculation whose output includes a reusable framing of the test, not just a winner. It doesn't discuss edge behavior (e.g., how multi-version tests with versions > 2 are handled), which keeps 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?

Three sentences with the core purpose front-loaded and then inputs, outputs and triggers in order; the middle sentence is a bit long and the 'not just that B won' aside is stylistic, but each sentence contributes distinct information rather than 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?

With no output schema, the description correctly carries the burden of describing returns: per-version visitor counts, days to run, and the framing output. Coverage is good for a 9-parameter tool, with only minor gaps around non-default power/confidence/versions semantics.

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 78% (high), so the schema already documents most of the 9 parameters, including units for baseline rate and MDP lift, plus defaults/ranges for power and confidence. The description only restates the three required inputs ('current conversion rate, the smallest lift worth detecting and the daily traffic') and adds no format or unit guidance 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 ('Plan an A/B test for marketing copy') and immediately details the mechanics: it consumes conversion rate, minimum detectable lift and daily traffic, and returns required sample size per version plus run duration. That scope is clearly distinct from siblings like read_ab_test_result or plan_marketing_copy, though neither sibling is named explicitly.

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 final sentence gives four concrete trigger intents ('how long to run a test', 'how much traffic they need', 'whether a test is worth running', 'what to test next'), which is stronger than implied usage. It stops short of the 5 bar because it names no alternative tool or exclusion condition (e.g., when to use read_ab_test_result or plan_marketing_copy instead).

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, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond them: it explains what the output contains (which of nine questions to answer, weight per reader, several answer options), that one option is always the established move, and the rationale (models default to overused moves that readers skim past).

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 usage, then the rationale for the 'one established move' design. It is on the long side and the opening format enumeration is list-heavy, but nearly every sentence carries routing or behavioral information 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 planning tool with no output schema, the description does what the schema can't: it characterizes the return (question list, weighting, multiple candidate answers drawn from real advertising, linked to the Persuasion Taxonomy). Combined with 100% parameter coverage, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and each parameter carries its own enum/value documentation, so the schema does the heavy lifting. The description only loosely names 'the goal, the reader and the offer', which maps to a subset of the eight parameters without adding format or syntax detail. 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?

States a specific verb (plan) and resource (marketing copy) up front, then enumerates the covered formats. It explicitly separates itself from the post-draft sibling 'diagnose_marketing_copy', so an agent can route between them 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 an explicit when-to-use ('call it before you draft, even when you're sure you know how to write the piece') and names the complementary tool and the condition for it ('when the draft is done, check it with diagnose_marketing_copy'). No guidance 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 already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: it explains the returned statistical measures and warns about reliability pitfalls like too few conversions, sample ratio mismatch, peeking, and testing too many versions at once. This is precisely the kind of added value expected when annotations are present.

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 front-loaded with the core action and outputs, then moves to warnings and usage triggers. It is efficient overall, though the list of trigger questions at the end is somewhat expansive. Every sentence contributes useful information, so it is well structured but slightly long.

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 appropriately explains the returned values and statistical warnings. It is nearly complete for a read-only analysis tool, but it omits any guidance on the confidence parameter and does not clarify how the intended_split default relates to the input. These are minor gaps against an otherwise thorough 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 75%, with the question, versions, and intended_split parameters documented in the schema, while confidence has no schema description. The description does not explain any parameter semantics, including the confidence parameter or the intended_split format. When schema coverage is moderately high, a baseline of 3 is appropriate because the schema does the heavy lifting and the description adds no parameter-specific meaning.

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

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

The description states a specific verb and resource: reading the result of an A/B test. It goes further by enumerating the outputs (conversion rate, lift, significance, confidence interval, chance to beat original) and warnings, which clearly distinguishes it from planning siblings like plan_ab_test. An agent can identify the correct tool without ambiguity.

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

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

It gives explicit usage triggers such as when someone shares test numbers or asks 'did my test win?', 'is this significant?', 'which version won?', and 'should I keep it running?'. It does not explicitly state when not to use it or name the alternative plan_ab_test, so it falls short of full when/when-not/alternatives guidance.

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